The PALM build script

The script to compile PALM and its utility programs is called palmbuild. It resides under .../trunk/SCRIPTS and is invoked by the automatic installer as part of the installation process. It can also be executed manually, e.g. in case of a PALM code update from the svn repository, or code modifications by the user. Each modification of the source code requires new compilation.

palmbuild

• is steered by settings, e.g. of compiler options, in the configuration file .palm.config.<configuration identifier>,
  
  
• compiles code based on the unix makefile mechanism,
  
  
• adds the created binaries to the directory MAKE_DEPOSITORY_<configuration identifier>,
  
  
• is automatically invoked by the PALM run script palmrun in case this doesn't find the respective MAKE_DEPOSITORY_<configuration identifier>.

Manual execution of palmbuild

Assuming a configuration file named .palm.config.default, you need to type the command

   palmbuild -c default

Since you can have different configuration files (for different compilers, compiler options, or hosts), you need to specify the configuration file to-be-used by the option -c. The suffix default in this example is the <configuration identifier>, which can be an arbitrary ASCII-character string.

After entering the command, informative messages will appear in the terminal:

#--------------------------------------------------------------------------# 
| palmbuild  1.0  Rev: 3523 $               Wed Nov 21 09:47:10 CET 2018   | 
| PALM code       Rev: 3524                                                | 
|                                                                          | 
| called on:   hostname (IP:111.11.111.111)                                | 
| config file: /home/username/palm/current_version/.palm.config.default    | 
| makefile:    /home/username/palm/current_version/trunk/SOURCE/Makefile   | 
| source path: /home/username/palm/current_version/trunk/SOURCE            | 
|                                                                          | 
| config. identifier: default                                              | 
| local depository:   /home/username/palm/current_version/MAKE_DEPOSITORY_ | 
|                     default                                              | 
| username:           username                                             | 
| address:            111.11.111.111                                       | 
| compiler:           mpif90                                               | 
| serial compiler:    ifort                                                | 
| make options:       -j 4                                                 | 
| cpp options:        -cpp -D__parallel ...                                | 
| compiler options:   -fpe0 -O3 ...                                        | 
| linker options:     -fpe0 -O3 ...                                        | 
#--------------------------------------------------------------------------# 

 >>> continue (y(es)/c(ontinue)/a(bort)) ? 

After confirmation (y(es)), compilation starts and compiler messages will appear. After successful completion, the binaries reside in the directory MAKE_DEPOSITORY_default under the path given by the variable base_directory in the configuration file. When invoking palmbuild locally for compilation of PALM on a remote computer, sources are copied via scp to the remote host, and the compiler is called via ssh on the remote host as well. Here, the MAKE_DEPOSITORY_default also lands in base_directory.

In case you have updated the PALM code, you need to call palmbuild again:

   cd ~/palm/current_version
   svn update trunk
   palmbuild -c default

If you have changed the compiler options in the configuration file and like to re-compile the PALM code with the new options, you need to touch the source code files in your working copy of the repository first,

   touch trunk/SOURCE/*.f90
   palmbuild -c default

because otherwise the make mechanism would see no changes in the source code and would not compile at all (message make: Nothing to be done). Alternatively, you may delete the MAKE_DEPOSITORY folder:

   rm -rf MAKE_DEPOSITORY_default
   palmbuild -c default

However, best practice would be to create individual .palm.config files for the different configurations, because this prevents from having to re-compile over and over again whenever modifying and working with just one single .palm.config file. Of course, palmbuild has to be executed for each configuration.

Automatic execution of palmbuild

palmbuild is automatically called by the PALM run script palmrun, if:

1. palmrun has been invoked manually by the user in a terminal, and, if
   
   
2. palmrun does not find a MAKE_DEPOSITORY folder for the configuration given by option -c, it calls palmbuild with the respective configuration identifier (e.g. palmbuild -c default in order to pre-compile PALM, or, if
   
   
3. palmrun is notified by option -s ) about modified SOURCE code in the working copy (.../trunk/SOURCE), or if the user has added USER_CODE to the respective JOBS directory given by palmrun-option -r.
   
   
   • palmrun puts the respective source files (plus all other files from the MAKE_DEPOSITORY) into a newly created folder named SOURCES_FOR_RUN_<ci>_<ri> in the directory given by configuration variable base_directory
     (<ci>: configuration identifier, <ri>: run identifier, specified by palmrun options -c and -r).
     
     
   • palmbuild copies this folder to directory $fast_io_catalog/SOURCES_FOR_RUN_<ci>_<ri> and compiles the user-interface and/or modified sources. Variable fast_io_catalog is defined in the configuration file.
     For remote jobs, the SOURCES_FOR_RUN folder is copied via scp and the compiler is invoked via ssh.

The automatically generated palmbuild call generally looks like this

   palmbuild -v -c <ci> -r <ri>

where <ci> and <ri> are as given by the respective palmrun options. An additional option -V is added if the corresponding palmrun option -V has been set. For explanations of the internal options see the table below.

palmbuild is never called by palmrun within a batch job, or by automatic calls of palmrun to generate restart jobs. Reasons are to avoid compilation within batch jobs (which may be very inefficient if the job runs on many cores), and because automatic restart runs should and can re-use the binaries that have been created by the initial run and are saved in the respective SOURCES_FOR_RUN folder.

palmbuild user options

option	default value	meaning
-c	default	Configuration identifier. Tells palmbuild which configuration file is to be used.
-v	---	Run in silent mode. Switches off most messages and prompts.

palmbuild internal options

option	default value	meaning
-r	---	Run identifier, as specified with palmrun option -r.
-V	---	Do not compile sources for the SOURCES_FOR_RUN folder.

How does palmbuild operate?

A detailed list of consecutive steps that are carried out will follow soon ...