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
). As new stable releases of the porting 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 porting
. 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:
do [cesrulib.cesr_com]vlgl_current control_program
do vlgl control_program (only after Sept. 27, 2005)
In order to build and link a debug version of the program, the command is:
do [cesrulib.cesr_com]vlgl_deb_current control_program
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
. 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 porting 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 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.
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
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 porting libraries
- 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
- 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.
- 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.
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>
cc /include=('cesrlib_inc') my_c_routine.c
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 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
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 Porting Libraries
There are 3 main types of changes necessary for compatibility with the porting 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 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