--- MITgcm/doc/devel_HOWTO.sgml 2010/05/15 01:44:50 1.13 +++ MITgcm/doc/devel_HOWTO.sgml 2010/05/28 01:47:32 1.14 @@ -1,6 +1,6 @@ @@ -303,7 +303,8 @@ Main code development - (formerly named "Tagging" ; this section needs an update) + (formerly named "Tagging" ; this section needs an update) + The intent of tagging is to create "known-good" checkpoints that developers can use as references. Traditionally, MITgcm tagging has @@ -393,7 +394,7 @@ For MITgcm, the process is similar. Typical commands are: - $ genmake -mods=../code + $ genmake2 -mods=../code $ make depend $ make @@ -404,9 +405,8 @@ The <filename>genmake2</> Utility - Please note that the older genmake is - deprecated and will eventually be replaced by genmake2. - This HOWTO only describes the newer tool. + (Note: the older genmake + has been replaced by genmake2) The first step in any MITgcm build is to create a Unix-style Makefile which will be parsed by @@ -462,6 +462,12 @@ an "options file" as specified by the command-line option -optfile='FILENAME' + + a packages.conf file (in the current + directory or in one of the "MODS" directories, see below) + which contains the specific list of packages to compile + + then checking certain dependency rules (the package dependencies), @@ -515,33 +521,6 @@ - -pdepend=/PATH/FILENAME - - - This specifies the dependency file used for packages. If - not specified, the default dependency file is - $ROOTDIR/pkg/pkg_depend. The syntax for this file is - parsed on a line-by-line basis where each line containes either a - comment ("#") or a simple "PKGNAME1 (+|-)PKGNAME2" pairwise rule - where the "+" or "-" symbol specifies a "must be used with" or a - "must not be used with" relationship, respectively. If no rule is - specified, then it is assumed that the two packages are compatible - and will function either with or without each other. - - - - - -pdefault=PKG - -pdefault='PKG1 [PKG2 PKG3 ...]' - - This option specifies the default set of packages - to be used. If not set, the default package list will - be read from - $ROOTDIR/pkg/pkg_default. - - - - -adof=/path/to/file -adoptfile=/path/to/file @@ -569,7 +548,6 @@ will be overridden by any identically-named sources within the "MODS" directories. The order of precedence for this "name-hiding" is as follows: - "MODS" directories (in the order given) @@ -581,7 +559,38 @@ The "standard dirs" (which may have been specified by the "-standarddirs" option) + + + + + -pgroups=/PATH/FILENAME + + This option specifies the file where package groups are + defined. If not set, the package-groups definition will + be read from + $ROOTDIR/pkg/pkg_groups. + + It also contains the default list of packages (defined + as the group "default_pkg_list") which is used + when no specific package list (file: packages.conf) + is found in current directory or in any "MODS" directory. + + + + + -pdepend=/PATH/FILENAME + + + This specifies the dependency file used for packages. If + not specified, the default dependency file is + $ROOTDIR/pkg/pkg_depend. The syntax for this file is + parsed on a line-by-line basis where each line containes either a + comment ("#") or a simple "PKGNAME1 (+|-)PKGNAME2" pairwise rule + where the "+" or "-" symbol specifies a "must be used with" or a + "must not be used with" relationship, respectively. If no rule is + specified, then it is assumed that the two packages are compatible + and will function either with or without each other. @@ -607,7 +616,7 @@ In general, it is best to use genmake2 on a "clean" directory that is free of all source (*.[F,f],*.[F,f]90) and header (*.h,*.inc) files. Generally, this can be accomplished in an - "un-clean" directory by running "make CLEAN" followed by "make + "un-clean" directory by running "make Clean" followed by "make makefile". @@ -620,16 +629,18 @@ simulator) executable using: - $ make CLEAN + $ make Clean $ make depend $ make - The "make CLEAN" step will remove any stale source files, include + The "make Clean" step will remove any stale source files, include files, and links. It is strongly recommended for "un-clean" directories which may contain the (perhaps partial) results of - previous builds. Such "debris" can interfere with the next stage of - the build. + previous builds. Such "debris" can interfere with the next stage of + the build. + A more agressive cleaning option, "make CLEAN", can be used to also + remove the executable and output files from a previous run. The "make depend" step will create a large number of symbolic links from the local directory to the source file locations. It also