Changes between Initial Version and Version 1 of doc/app/palmbuild

Timestamp:

Aug 30, 2018 8:38:22 AM (6 years ago)

Author:

raasch

Comment:

--

doc/app/palmbuild

@@ +1 @@
+= {{{palmbuild}}} technical description =
+
+== Introduction == 
+{{{palmbuild}}} is the shell script to compile PALM and further utilities required for pre- and postprocessing the PALM data. It is invoked by the [wiki:doc/install/automatic automatic installer] as part of the installation process, or it can be called manually, and puts the created binaries in a folder named {{{MAKE_DEPOSITORY_<ci>}}}, where {{{<ci>}}} is the configuration identifier. It is also automatically invoked by the script [wiki:doc/app/palmrun palmrun] in two different ways, but only if {{{palmrun}}} is called manually. If {{{palmrun}}} cannot find pre-compiled PALM sources, it calls {{{palmbuild}}} to create the MAKE_DEPOSITORY. Furthermore, manual calls of {{{palmrun}}} always call {{{palmbuild}}} to generate a specific folder (names SOURCES_FOR_RUN_...) that contains all binaries for the specific run, which may be re-used by automatic restart runs (see ''automatic calls'' further below).
+
+Manual calls of {{{palmbuild}}} are required in case that a new PALM code version has been checked out from the repository, or if a modified working copy of the code shall be used for PALM runs.
+
+{{{palmbuild}}} is steered by options as well as settings in the [wiki:doc/app/palm_config configuration file]. It compiles code based on the unix makefile mechanism.
+
+\\
+== How to call {{{palmbuild}}} manually ==
+Manual calls of {{{palmbuild}}} are used to generate or update the compiled PALM sources (binaries). Specific informations e.g. about the compiler and the compiler options to be used need to be specified in the [wiki:doc/app/palm_config configuration file]. Relevant variables to be specified are ''source_path'', ''user_source_path'', ''compiler_name'', ''compiler_name_ser'', ''cpp_options'', ''make_options'', ''compiler_options'' and ''linker_options''. See [wiki:doc/app/palm_config configuration file] for a description of these variables. 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 {{{palmbuild}}}. Assuming a configuration file {{{.palm.config.abcde}}}, you need to enter
+{{{
+   palmbuild -h abcde
+}}}
+{{{abcde}}} is the so-called ''configuration identifier''. After entering the command, informative messages will appear in the terminal:
+{{{
+#------------------------------------------------------------------------# 
+| palmbuild  1.0  Rev: 3210 $              Thu Aug 30 09:29:56 CEST 2018 | 
+| PALM code       Rev: 3220                                              | 
+|                                                                        | 
+| called on:   bora (IP:130.75.105.103)                                  | 
+| config file: /home/raasch/palm/current_version/.palm.config.abcde      | 
+| makefile:    /home/raasch/palm/current_version/trunk/SOURCE/Makefile   | 
+| source path: /home/raasch/palm/current_version/trunk/SOURCE            | 
+|                                                                        | 
+| config. identifier: abcde                                              | 
+| local depository:   /home/raasch/palm/current_version/MAKE_DEPOSITORY_ | 
+|                     abcde                                              | 
+| username:           raasch                                             | 
+| address:            130.75.105.103                                     | 
+| compiler:           mpif90                                             | 
+| serial compiler:    ifort                                              | 
+| make options:       -j 8                                               | 
+| cpp options:        -cpp -D__parallel ......                           | 
+| compiler options:   -fpe0 -O3 ......                                   | 
+| linker options:     -fpe0 -O3 ......                                   | 
+#------------------------------------------------------------------------# 
+
+ >>> continue (y(es)/c(ontinue)/a(bort)) ?  
+}}} 
+If {{{y}}} is entered, compilation will be started and compiler messages will appear. After successful completion, you will find the binaries in the directory given in the configuration file by {{{base_directory}}} under the folder name {{{MAKE_DEPOSITORY_abcde}}}.
+
+In case of a configuration file for PALM runs on a remote host, sources are copied via {{{scp}}} to the remote host and the compiler is called via {{{ssh}}} on the remote host too. Folder {{{MAKE_DEPOSITORY_abcde}}} is created under {{{base_directory}}} on the remote host.
+
+In case you have updated the PALM code, you need to call {{{palmbuild}}} again:
+{{{
+   cd ~/palm/current_version
+   svn update trunk
+   palmbuild -h abcde
+}}}
+
+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 -h abcde
+}}}
+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_abcde
+   palmbuild -h abcde
+}}}
+
+If you have more than one configuration file, you need to call {{{palmbuild}}} separately for each configuration.
+
+For further information see the [wiki:doc/app/palmbuild detailed palmbuild description].
+
+\\
+== Automatic calls of {{{palmbuild}}} from {{{palmrun}}}
+if a [wiki:doc/app/userint user-interface] is used, or if {{{palmrun}}} option {{{-s}}} is used to force compilation of specific routines. Actually, {{{palmbuild}}} is called in each manual call of {{{palmrun}}} to provide various files for the respective run (including the binaries), which are put in a specific folder that is used by all runs of an automatic job chain.