Building and Linking Against CESR Porting Codes on VMS

Note: All VMS systems were shut down on January 17, 2017.

The information below is obsolete.

Default Code Builds Will Be Against the CESR Porting Libraries Starting Sept. 27th!!

Maintenance of the CESR Porting Codes on VMS

The CESR Code Librarian maintains versioned releases of the CESR Porting Libraries on VMS. These are releases that have first been built and tested under the OSF operating system and then transferred to the control system where the VMS binaries are created. The active version of these libraries is designated the current release. It is a stable version against which all control system codes should be built and linked by default. In the event of significant new features being added to the porting libraries, support for building and linking against a development ( devel ) version of the libraries has also been provided (see below). As new stable releases of the porting libraries become available, they will be designated as the current release (in consultation with the CESR software group) for general use on the control system.

Basic Compiling and Linking Instructions for Control System Codes

Special versions of the VLGL command files have been created to compile and link against the porting libraries. These command files are designed for compatibility with the existing VLGL syntax so that they can be directly substituted for a standard, old-style do vlgl command. Nevertheless, a number of code updates are present in the porting libraries which may lead to failed builds. A summary of the changes most likely to affect control system users can be found below.

Starting on Sept. 27, 2005, the default CESR build scripts, u:[cesr.com]vlgl.com and u:[cesr.com]vlgl_deb.com, will be modified so that default builds take place using the CESR Porting Libraries.

Code Builds Against the CESR Porting Libraries

In their simplest usage, the vlgl scripts can be used to compile and link a program called control_program.f77 (or .f90) against the current release of the the porting libraries by typing any of the following:

@[cesrulib.cesr_com]vlgl_current control_program
or 
do [cesrulib.cesr_com]vlgl_current control_program
or
do vlgl control_program                                (only after Sept. 27, 2005)

In order to build and link a debug version of the program, the command is:

@[cesrulib.cesr_com]vlgl_deb_current control_program
or 
do [cesrulib.cesr_com]vlgl_deb_current control_program
or 
do vlgl_deb control_program                            (only after Sept. 27, 2005)

More involved examples are described below.

Code Builds Against the Old CESR Libraries

For those who need to build/link using the old system, builds will be supported (at least temporarily), by using the scripts: u:[cesr.com]vlgl_oldstyle.com and u:[cesr.com]vlgl_deb_oldstyle.com. A simple build example is:

do vlgl_oldstyle control_program           (production build)
or
do vlgl_deb_oldstyle control program       (debug build)

Please note that vlgl_oldstyle.com and the old vlgl.com are structurally not the same. In the new build environment, the vlgl_oldstyle command files execute an extra command file on startup, u:[cesr.com]set_lib_oldstyle.com, which configures a number of VMS logicals so that the build will work properly.

In general, support for old versions of libraries such as BMAD, DCSLIB, and BMADZ will be minimal or non-existent. Furthermore, some control system-only libraries (eg, SCIR_POSITION) will only be maintained against the porting libraries . Thus it is quite likely that many old-style builds will eventually fail. Users should be aware of this and are urged to migrate to the new build system as soon as possible.

Detailed Description of the New Build Tools

Command Files

There is a 3-layer hierarchy of command files in the new system:

• The vlgl*.com scripts
• The set_lib.com script which configures the build to point to a particular porting libraries release
• The do_vlgl*.com scripts which control the linking process

VLGL Files

There are 4 vlgl_*.com files provided with the new build system:

vlgl_current.com

Builds against the production (ie, non-debug) versions of the libraries in the current release.

vlgl_deb_current.com

Builds against the debug versions of the libraries in the current release.

vlgl_devel.com

Builds against the production (ie, non-debug) versions of the libraries in the devel release.

vlgl_deb_devel.com

Builds against the debug versions of the libraries in the devel release.

These files can be found in the u:[cesrulib.cesr_com] directory.

The new vlgl command files now take a 3rd optional argument in addition to the 2 arguments used by the old versions. The arguments (which must be supplied in fixed order) are:

p1

A comma-separated list of files (without file suffix) to compile and link.

p2 (optional)

A comma-separated list of pre-compiled objects and/or object libraries (without file suffix; remember to add /lib specification to object libraries) to be linked against.

p3 (optional)

A comma-separated list of user-specificed directories to add to the beginning of the search path for F90 module files and/or include files. The standard search order is the local directory followed by the relevant directories in the CESR Porting Libraries release area, followed by the u:[cesr.modules] directory. When a user-specified list of directories to search is added, it comes immediately after the local directory in the search list.

SET_LIB File

The first action taken by the new vlgl command files is to run the library setup script, u:[cesrulib.cesr_com]set_lib.com, which insures that the family of CESR_ logicals are pointing to the proper version of the porting libraries release and also creates the cesrlib_inc symbol which contains the proper search path for include files and F90 module files. The set_lib command file takes up to 3 arguments (in any order):

p1 (optional)

Release version:

current

or

devel

[Default:

current

]

p2 (optional)

Debug level (production or debug):

prod

or

deb

[Default:

prod

]

p3 (optional)

Optional "silent" keyword to suppress typeouts

DO_VLGL Files

The new vlgl command files next execute the relevant do_vlgl script to link an executable. There are two linking scripts:

do_vlgl_port.com

Links against the production versions of the control system-only libraries and the porting libraries

do_vlgl_deb_port.com

Links against the debug versions of the control system-only libraries and the porting libraries

Both of these scripts can be found in the u:[cesrulib.cesr_com] directory.

Directory Structure of the New Library System

Under the new build system, there are 3 classes of CESR libraries:

• Control System-ONLY libraries
  • GRLIB
  • STULIB
  • VMPMLIB
• CESR libraries maintained as part of the CESR Porting Libraries . The directory containing the sources for these libraries is pointed to by the CESR_CVSSRC logical. Object libraries can be found in the CESR_LIB area while F90 module files can be found in the CESR_MOD area.
  • BeamInstSupport
  • bmad
  • bmadz
  • c_utils
  • CesrBPM
  • cesr_utils
  • dcslib
  • MPMnet
  • nonlin_bpm
  • recipes_f_90_lepp
• 3rd-party libraries maintained as part of the CESR Porting Libraries . The directory containing the sources for these libraries is given by the CESR_PKG logical. Object libraries can be found in the PKG_LIB area while F90 module files can be found in the PKG_MOD area.
  • cfortran
  • forest
  • PGPLOT
  • recipes_f_90
  • recipes_c_ansi
  • xsif

Viewing Code Sources

Detailed listings of the codes maintained as part of the CESR Porting Libraries is available via the ViewCVS repository viewing utility.

• View libraries that are part of the CESR_CVSSRC area
• View libraries that are part of the CESR_PKG area

Advanced Code Build Instructions

Explicitly Compiling Your Own Routines (Using set_lib.com)

On some occasions it is necessary to explicitly compile your own routines that may use F90 modules and/or include files from the porting libraries. This can be done in the following way:

@[cesrulib.cesr_com]set_lib <optional arguments>
f90/include=('cesrlib_inc') my_F_routine.f90
cc /include=('cesrlib_inc') my_c_routine.c

The cesrlib_inc symbol contains the necessary search path for F90 modules that are part of the porting libraries as well as include directories that contain header and include files. Note that the use of the search path method for include files means that users should specify include files from the porting libraries without absolute directories in order to pick up the correct version from the specified release.

Setting Up MMS and GNU Makefile Targets

Examples can be found in:

• u:[cesr.cesrv.current]descrip.mms for a working MMS example
• u:[cleo31.energy_program.src.bin]Makefile. for a working GNU Makefile example

Building Against the Development Version of the Porting Libraries

In the event that you need to build your code against the development (ie, the testing) release of the porting libraries (for instance, this may be the case if you want to take advantage of a new feature being introduced in BMAD), you simply need to substitute devel for current in the above commands. For instance, to link a debug executable against the development release, the command is:

@[cesrulib.cesr_com]vlgl_deb_devel control_program

Code Modifications Required for Compatibility with the CESR Porting Libraries

There are 3 main types of changes necessary for compatibility with the porting libraries versions of the CESR codes:

1. CESR F90 codes (eg, BMADZ, BMAD, DCSLIB) are configured for double-precision arguments. The precision of arguments being passed to subroutines/functions in these libraries should be specified using the rp precision variable. An example of the necessary syntax is available in the twiss_track_test.f90 program.
2. Data structures in F90 codes have had numerous modifications relative to the old-style VMS versions of the code. For example, BMAD coord structs are now allocatable structures.
3. Include statements that refer to library source areas that are part of the porting libraries should be referenced with NO path attached

The program twiss_track_test.f90 provides a simple example showing the use of the (rp) definition and allocatable coord structs.

Known Issues and Problems

The following are known issues

• GETF and LISTF utilities do not yet indicate files in the proper source areas. The correct source areas can be found by means of the CESR_CVSSRC and CESR_PKG logicals and searched locally if there are questions about particular routines.
• Linking of programs with C++ components on VMS (eg, BMADZ) is presently not operational on VMS

---

Please contact Mark Palmer with questions or problems about this page.

Created      :  -- Main.MarkPalmer - 09 Jun 2005
Last Modified:  -- Main.MarkPalmer - 27 Sep 2005