Building and Linking Against CESR Portable Code on VMS

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

The information below is obsolete.

ALERT! Default Code Builds Are Performed Against the CESR Accelerator Libraries ALERT!

Maintenance of the CESR Portable Code on VMS

The CESR Code Librarian maintains versioned releases of the CESR Portable 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 portable 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 portable 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 portable 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 portable libraries which may lead to failed builds. A summary of the changes most likely to affect control system users can be found below.

ALERT! As of Sept. 27, 2005, the default CESR build scripts, u:[cesr.com]vlgl.com and u:[cesr.com]vlgl_deb.com, now execute builds using the CESR Portable Libraries.

Code Builds Against the CESR Portable 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 portable libraries by typing any of the following:
do vlgl control_program
In order to build and link a debug version of the program, the command is:
do vlgl_deb control_program
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)
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 portable 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 portable 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:
Builds against the production (ie, non-debug) versions of the libraries in the current release.
Builds against the debug versions of the libraries in the current release.
Builds against the production (ie, non-debug) versions of the libraries in the devel release.
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:
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 Portable 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.


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 portable 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:
p2 (optional)
Debug level (production or debug):
p3 (optional)
Optional "silent" keyword to suppress typeouts


The new vlgl command files next execute the relevant do_vlgl script to link an executable. There are two linking scripts:
Links against the production versions of the control system-only libraries and the portable libraries
Links against the debug versions of the control system-only libraries and the portable 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
  • CESR libraries maintained as part of the CESR Portable 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 Portable 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 Portable 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. For users trying to do local builds of C/C++ code, they must execute a

set process/parse_style = traditional

in their build window before building. The rest of this process can be done in the following way in a DCL command file:
$ @[cesrulib.cesr_com]set_lib <optional arguments>
$! For an F77/F90 file that requires C-preprocessing and compilation
$ cc/preprocess_only/comments=as_is/include=('cesrlib_inc') my_F_routine.f90
$ f90/source_form=free/include=('cesrlib_inc') my_F_routine.i /object
$! For an F90 file that only needs to build against know F90 modules, but does not have any local pre-processer directives
$ f90/include=('cesrlib_inc') my_F_routine.f90 /object
$! For C file preprocessing/compilation
$ cc /include=('cesrlib_inc') my_c_routine.c /object
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 Portable Libraries

ALERT! 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 Portable Libraries

There are 3 main types of changes necessary for compatibility with the portable 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 portable 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.

Code build of local version of CESR library.

If one needs to compile local version of CESR library, for example bmad, the following steps are required:

Make a local copy of the bmad source:
 backup CESR_PORTING:[cesr_libs.<release>.src.bmad...] [.bmad...] 
where release is the version in the VMS release that you want to work from. A shortcoming of the VMS GNU makefile system is that you will need to make local copies of the
areas for your library to build against. The local copies should be put in directories at the same level as the library you are building, ie:
 backup CESR_PORTING:[cesr_libs.<release>.modules...] [.modules...] 
 backup CESR_PORTING:[cesr_libs.<release>.src.include...] [.include...] 

In your bmad (or other local library) directory, modify makefile.vms by setting the following variables:
where packages_area provides the basename of the packages area to use. For example, set
You must also set the absrcdir directory to your local library path.
 absrcdir:= u:[cesr.my_local.bmad] 
Finally, the CESRLIB variable should point to the release from which you made your local copy.
CESRLIB:= <release>

Then type gmake in the library directory to start your build.

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 and NOT SUPPORTED

Please contact Mark Palmer with questions or problems about this page.
Created      :  -- Main.MarkPalmer - 09 Jun 2005
Last Modified:  -- Main.MarkPalmer - 06 Sep 2008
Topic revision: r19 - 18 Jan 2017, SeldenBallJr

  • ACC/ACL Web

  • CLASSE Computing Info

Create personal sidebar

This site is powered by FoswikiCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding CLASSE Wiki? Send feedback