Changes between Version 1 and Version 2 of doc/app/palmbuild_quickstart

Timestamp:

Aug 30, 2018 8:40:48 AM (6 years ago)

Author:

raasch

Comment:

--

doc/app/palmbuild_quickstart

@@ -1 +1 @@
 = Quickstart guide for compiling PALM with {{{palmbuild}}} =
 
-== Introduction == 
-PALM can be run in different modes: 
-* [#interactive interactive mode] | PALM executes (almost) immediately within your terminal session after entering the {{{palmrun}}} command.
-* [#batch batch mode] | PALM job is submitted by {{{palmrun}}} to a queuing/batch system (e.g. PBS, ...), where it is scheduled for execution.
 
-A batch system is a must-have on high-performance computers, and a nice-to-have for computers that are shared among a larger number of users.
-The handling of PALM differs between interactive and batch mode, and it slightly varies, depending if the PALM job is submitted to the
+{{{palmbuild}}} is the shell script to compile PALM.
+
+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''. {{{default}}} is assumed as configuration identifier, if option {{{-h}}} is omitted. 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].