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.
Default Code Builds Are Performed Against the CESR Accelerator Libraries
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
). As new stable releases of the portable libraries
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
. 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
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
. 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
. 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.
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
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
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
- 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.
- 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.
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
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
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
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
in the above
commands. For instance, to link a debug executable against the development release, the command is:
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:
- 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.
- 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.
- 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...]
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...]
(or other local library) directory, modify
by setting the following variables:
provides the basename of the packages area to use. For example, set
You must also set the
directory to your local library path.
Finally, the CESRLIB variable should point to the
from which you made your local copy.
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