This file contains the latest "mk" script for the University of Victoria Earth System Climate Model (UVic_ESCM). The individual file may be accessed through the main UVic_ESCM link. Compressed, the file is approximately 19 kb. Uncompressed, the file is approximately 110 kb. When untarred, the mk file will be placed in a UVic_ESCM subdirectory. This file may be untarred in the same directory as the UVic_ESCM.2.9.tar file but any existing mk file (from previous model versions) will be over written. You may want to make a backup of any old mk script until you are satisfied that the new script is working correctly for all model versions. "mk" is a perl script that controls the compiling and execution of the model. "mk h" will generate a "log" file similar to the one copied below. This includes a description of commands, setup for the current directory, a general description of the script, variables that can be set and a list of available model options. To uncompress the file: gunzip UVic_ESCM.mk.tar.gz tar -xvf UVic_ESCM.mk.tar File list: UVic_ESCM/ UVic_ESCM/mk -------------------------------------------------------------------------------- mk [Command [[Path]Version] [String]] -------------------------------------------------------------------------------- Command: 'q' makes executable and submits to a queue (includes mk s) 'r' makes and runs an executable locally (includes mk e) 's' makes executable and submit scripts (includes mk e) 'e' makes an executable (includes mk o) 'o' makes all object files (includes mk f) 'f' makes all compilable files in code 'file' to make a file (eg. 'mk atmos.o' or 'mk atm.h') 'c' clears the code directory 'h' writes help to a log file -------------------------------------------------------------------------------- Path: model version directory path (default searches $PATH) Version: model version directory (only used if not in mk.in or $HOME/.mk/mk.in) String: help for mk.in variables containing string (only used if Command = 'h') -------------------------------------------------------------------------------- Any command will create a local, default mk.in file if one is not found. -------------------------------------------------------------------------------- General description: mk is used to create, compile, link and run code. The program works in a similar way to 'make' in that the minimum amount of code is recompiled when changes are made. mk reads the model configuration from 'mk.in' and 'mk.ver' files. If important definitions are changed, mk will detect these and 're-mk' the code. mk looks for configuration definitions in the initial directory, then the $HOME/.mk directory and finally in a UVic_ESCM installation subdirectory. Only settings in a local mk.in file are used. If a local mk.in file is missing, the model version must be specified after the mk command. A default version of mk.in is then copied from the $HOME/.mk directory and if one is not found there, from a UVic_ESCM installation subdirectory. The Version_Directory variable is always set at the top of a copied default mk.in file so the version only has to be specified once. mk.ver files are treated differently. Settings in all mk.ver files are read but the priority for settings is from the mk.ver files in the local directory, then the $HOME/.mk directory and then a UVic_ESCM installation subdirectory. mk uses 'Source_Directory' definitions as the basis for all other definitions. Source directories may exist anywhere but usually are under a model version directory. Multiple source directories are specified with a bracketed index. If a variable does not specify a source directory index, then an index of zero is assumed. Undefined variables will usually get their definitions from lower numbered source directories so specifying a variable without an index specifies that variable for all source directories (until a different definition is specified). The version directory also usually contains a system wide 'mk.ver' file which has the system default values. The version directory may also contain input files, library files or run files. An update level for source directories may be specified and mk will use files in the update level source directories before other specified source directories. The source directories must have the same name under the 'Updates_Level' directory for them to be recognized. The updates level source directories must contain all code that has been changed from the original version source directories. No earlier update level sources are used. mk allows for multiple executables, executable directories, code directories and data directories but only one per source directory. Usually an executable directory contains the executable input and output files and code and data directories. The code directory contains readable model code and an object and dependency directory. It may also have a backup directory. The model is run in the executable directory. You may run executables on the local machine with 'mk r' but you can also run multiple executables or queue the executables with 'mk q'. This copies a specified perl script run file to 'Executable_File'.run in the executable directory. The perl script run file usually exists under the version directory and may be model or system specific. Some mk defined variables are suppled at the beginning of the run file. See examples. The 'Executable_File'.run file should be removed automatically when the executable finishes. If mk finds the run file in the executable directory, it will not run another executable until 'Executable_File'.run is removed. The command 'mk h' will print to a log file the commands that can be used, this description and all available preprocessor options. -------------------------------------------------------------------------------- Operating system derived variables used by mk: -------------------------------------------------------------------------------- Home: A directory used in searching for mk.in files in 'HOME/.mk'. It is derived from the system variable 'HOME'. Machine_Name: This is added to various variables to make them machine dependent. Machine_Name is derived from the system variable 'MK_MACHINE_NAME' or if this is not defined, from the command 'uname -n'. Check that this gives the expected response if you wish to use machine dependent variables. Machine_Name is converted to all lower case for use in machine dependent variables. This variable may also be specified in mk.in or mk.ver files. Mk_Path: Path that is used to search for Version_Directories. It is derived from the system variable 'PATH'. Operating_System: This is added to various variables to make them operating system dependent. Operating_System is derived from the system variable 'MK_OSTYPE' or if this is not defined, from from the command 'uname -s'. Check that this gives the expected response if you wish to use operating system dependent variables. Operating_System is converted to all lower case for use in system dependent variables. This variable may also be specified in mk.in or mk.ver files. User: Name used if an email address is requested by a run script. It is derived from the system variable 'USER' or read from a mk.in or mk.ver file. -------------------------------------------------------------------------------- Equality_Character: -------------------------------------------------------------------------------- Character that separates a variable name from it's value or setting in a mk.in file. It can be changed to any character sequence multiple times in the file. Default is '='. -------------------------------------------------------------------------------- Alphabetical list of variables that may be set for each Source_Directory: (see examples in mk.in or mk.ver files) -------------------------------------------------------------------------------- Auto_Update: Flag to automatically update code. Default is 'false'. If true and source code is newer than then the version in code, mk will ask if you want the code updated. Be careful if using this with No_Warnings. Backup_Directory: Directory that exists under the code directory and contains backup files. Optional. Files are copied from the Code_Directory when the code is cleared with 'mk c'.If the directory does not exist, it will be created. Change_Mount: A list of old and new file system mount points separated by a space. Optional. Only used if queueing on a distributed system where a common mount point is required but not given by 'pwd'. Directories starting with the old mount point are replaced by the new. For example, if 'Change_Mount = /u01 /u', the '/u01/home/' directory would become '/u/home/'. Directories are only changed if the new directory exists. Code_Directory: Directory which contains readable code files. It also usually contains the Dependency_Directory, Object_Directory and Backup Directory. Default is 'code'.If the directory does not exist, it will be created. Code_Extension: Code extension after preprocessing (include files retain an Include_Extension). Only the first in a list is used. Default is 'Code_Extension_is_undefined'. Compiler_'Source_Extension' (see Machine_Name and Operating_System): Compiler with options. Compiler may be set differently for each source code extension. The last option flag should be set to create object code. The syntax for compiling is: 'Compiler_Source_Extension file.Source_Extension'. Compilers may also be set for parallel or specific operating systems or machines. Compiler_Parallel definitions are only used if Number_Processors is greater than one. Note: if Compiler_Source_Extension is defined, it will overrule other definitions. The order of priority is: Compiler_'Source_Extension' Compiler_Parallel_'Source_Extension'_'Machine_Name' Compiler_Parallel_'Source_Extension'_'Operating_System' Compiler_Parallel_'Source_Extension' Compiler_Parallel_'Machine_Name' Compiler_Parallel_'Operating_System' Compiler_Parallel Compiler_'Source_Extension_Machine_Name' Compiler_'Source_Extension_Operating_System' Compiler_'Machine_Name' Compiler_'Operating_System' Compiler Compiler_Default Compress_Command: Command for compressing or taring the code directory. Optional. Syntax is: 'Compress_Command Code_Directory.Compress_Extension Code_Directory'. Code_Directory is removed after compression or tarring. Compress_Extension: Extension for a compressed or tarred Code_Directory. Data_Directory: Directory which will contain data files. Optional. Data files are copied from Data_Source if any are missing. If the directory does not exist, it will be created. Data_Source: Directory which will contain data source files. Optional. Default is Version Directory/Data_Directory. If not found locally, mk will look in the Version Directory. Definitions_Down: Flag to spread definitions downward through source directories. Any undefined variable will get its value from from the next highest source directory that has the variable defined. Default is true. Definitions_Up: Flag to spread definitions upward through source directories. Default is false. Dependency_Directory: Directory that exists under the code directory and contains dependency files for the mk program. Default is Code_Directory/D.If the directory does not exist, it will be created. End_String: A string that is passed to a run file which can be checked to indicate the successful completion of a run. This variable is not passed to the run file if set to false or only spaces. Executable_Directory: The directory where the Executable_File will be run. Default is the directory where mk was run. Executable_File: As it sounds. Optional (but recommended!) Include_Extension: Extensions for include files. May be a list separated by spaces. Default is Include_Extension_is_undefined. Input_File: A file which is usually read by the Executable_File. Optional. Libraries (see Machine_Name and Operating_System): Libraries which are used in linking code. Optional. The syntax for linking is: Linker Executable_File Object_Directory/*.Object_Extension Libraries Libraries may also be set for parallel or specific operating systems or machines.Libraries_Parallel definitions are only used if Number_Processors is greater than one. Note: if Libraries is defined, it will overrule other definitions. The order of priority is: Libraries Libraries_Parallel_'Machine_Name' Libraries_Parallel_'Operating_System' Libraries_Parallel Libraries_'Machine_Name' Libraries_'Operating_System' Libraries_Default Libraries_Directory (see Machine_Name and Operating_System): Library paths which are used in linking code. Optional. These may be a list which includes several paths. Libraries_Directory may also be set for parallel or specific operating systems or machines. If a directory is not found, mk will look in Version_Directory/lib. Library_Directory_Parallel definitions are only used if Number_Processors is greater than one. Note: if Libraries_Directory is defined, it will overrule other definitions. The order of priority is: Libraries_Directory Libraries_Directory_Parallel_'Machine_Name' Libraries_Directory_Parallel_'Operating_System' Libraries_Directory_Parallel Libraries_Directory_Directory_'Machine_Name' Libraries_Directory_'Operating_System' Libraries_Directory_Default Libraries_Directory_Prefix (see Machine_Name and Operating_System): Prefix for Libraries_Directory. Default is '-L'. Libraries_Directory_Prefix may also be set for operating systems or machines. Note: if Libraries_Directory_Prefix is defined, it will overrule other definitions. The order of priority is: Libraries_Directory_Prefix Libraries_Directory_Prefix_'Machine_Name' Libraries_Directory_Prefix_'Operating_System' Libraries_Directory_Prefix_Default Linker (see Machine_Name and Operating_System): Linker which is used in linking code. Optional. The syntax for linking is: 'Linker Executable_File Object_Directory/*.Object_Extension Libraries' Linker may also be set for parallel or specific operating systems or machines. Linker_Parallel definitions are only used if Number_Processors is greater than one. Note: if Linker is defined, it will overrule other definitions. The order of priority is: Linker Linker_Parallel_'Machine_Name' Linker_Parallel_'Operating_System' Linker_Parallel Linker_'Machine_Name' Linker_'Operating_System' Linker_Default Log_File: Log file which contains output from mk. Default is log. Machine_Name: This is added to various variables to make them machine dependent. This setting will overrule system definitions. Mk_Include_File: File which contains mk settings for including in code. Optional. Mk_Include_Start: Characters written before settings in Mk_Include_File (eg. print*,). Optional. Mk_Include_Width: Maximum length of settings written to Mk_Include_File. Optional. Model_Options: Model options for the Preprocessor or Compiler. Optional. Module_Extension (see Machine_Name and Operating_System): Extension for modules files that need to be available for compiling. Optional. Module_Extension may also be set for operating systems or machines. Note: if Module_Extension is defined, it will overrule other definitions. The order of priority is: Module_Extension Module_Extension_'Machine_Name' Module_Extension_'Operating_System' Module_Extension_Default Nice: Nice value sent to the Run_File so the Run_File can set the job priority. Optional. Notify_User: Email address that can be used by the run scripts to notify a user when a job has finished. If just the domain name is supplied (must start with the 'at' symbol), the user name (see User) will be added. Lists of users will be passed on but all spaces are removed. If set to false or only spaces, Notify_User is not sent to the Run_File and automatic notification may not be done. No_Warnings: Flag that turns off all warnings from mk. Default is false. If true, code may be deleted without warning. Be careful. Number_Processors: Number of processors. Default is 1. If greater than 1, it will indicate a parallel run. Operating_System: This is added to various variables to make them operating system dependent. This setting will overrule system definitions. Object_Directory: Directory that exists under the code directory and contains object files. Default is Code_Directory/O. If the directory does not exist, it will be created. Object_Extension: Extensions for object files. Only the first in a list is used. Default is Object_Extension_is_undefined. Option_Prefix (see Machine_Name and Operating_System): Prefix for Preprocessor options. Default is '-D'. Option_Prefix may also be set for operating systems or machines. Note: if Option_Prefix is defined, it will overrule other definitions. The order of priority is: Option_Prefix Option_Prefix_'Machine_Name' Option_Prefix_'Operating_System' Option_Prefix_Default Output_File: Standard output from the executable. Optional. Preprocessor (see Machine_Name and Operating_System): Preprocessor used to apply Model_Options. Optional. Preprocessor may also be set for operating systems or machines. If Note: if Preprocessor is defined, it will overrule other definitions. The order of priority is: Preprocessor Preprocessor_'Machine_Name' Preprocessor_'Operating_System' Preprocessor_Default Preprocessor_Code: Flag to leave code as preprocessed files. Default is false. Preprocessor_compile: Flag to use the compiler for preprocessing. Default is false. If this option is used the compiler definitions are modified. mk will look for the string defined by Preprocessor in Compiler_Source_Extension and replace it with Preprocessor followed by all Model_Options (with Option_Prefix included). Preprocessor and Option_Prefix may have to be set differently than when not using this option. Remote_Directory: Directory that triggers running on a remote machine. Optional. If Executable_Directory starts with Remote_Directory then Machine_Name is set to Remote_Machine. Remote_Machine (Remote_Directory): Machine_Name for running on a remote machine. Set to false to never run remotely. Run_Copy: A space separated list of files or directories that are copied to the Run_Directory. Optional. Run_Directory: A remote directory for running the Executable_File. Only used with a Run_File. Run_Directory may be used to run the Executable_File on a local scratch directory. Optional. Run_File (see Machine_Name and Operating_System): Files used to submit Executable_File to a queue. Optional. Run_File may also be set for operating systems or machines. Run_File_Parallel definitions are only used if Number_Processors is greater than one. If Note: if Run_File is defined, it will overrule other definitions. The order of priority is: Run_File Run_File_Parallel_'Machine_Name' Run_File_Parallel_'Operating_System' Run_File_Parallel Run_File_'Machine_Name' Run_File_'Operating_System' Run_File_Default Run_File_Local (see Run_File): Run_File to be used if running locally (with 'mk r'). Set to false to run locally without a Run_File. Search_Path: Path that mk will search for a Version_Directory. Optional. May be a space separated list. Source_Comment_Character: Unless set to false, mk will add the Source_Comment_Character followed by the name of the source file to the beginning of code and include files. Optional. Source_Directory: Directories which contain source or include files. If not found locally, mk will look in the Version Directory. Source_Extension: Extensions for source files. May be a list separated by spaces. Default is Source_Extension_is_undefined. Step_Start_File: Unless undefined or set to false, an executable that will be run before each step in a multi-step run. Optional. Step_End_File: Unless undefined or set to false, an executable that will be run after each step in a multi-step run. Optional. Uncompress_Command: Command for uncompressing or untaring the code directory. Syntax is: Compress_Command Code_Directory.Compress_Extension Updates_Level: Directory with updated source code. Optional. Default is latest. Often set to a number which determines the updates level. If the directory is not found under 'updates' locally it will be searched for in Version_Directory/updates. If set to latest, Version_Directory/updates will be searched for the highest number. User Name used if an email address is requested by a run script. This setting will overrule system definitions. Version_Directory: Directory which determines the model version. Must be defined but may be set as a command option.