ymake(1NCARG)

NAME
ymake - C preprocessor interface to the make utility

SYNOPSIS
ymake [-config configpath] [-noproject] [-Ddefine] [-Idir]

OPTIONS
The following command line options may be passed to ymake:

-config
    This option should only be used by ymkmf or by an existing Makefile. It is used to indicate that the ymake program is being used from within the NCARG Distribution tree, and to indicate where the config directory is found.

-noproject
    This option should only be used if ymake is being used to manage software other than NCAR Graphics. It causes ymake to not use a Project file.

-Ddefine
    This option is passed directly to cpp. It is typically used to set directory-specific variables. For example, the NCAR Graphics distribution uses this flag to set TOPDIR to the name of the directory containing the top of the distribution and CURDIR to the name of the current directory, relative to the top. Multiple -D flags may be sent to ymake.

-Idirectory
    This option is passed directly to cpp. It is typically used to indicate the directory in which the ymake template and configuration files may be found. Multiple -I flags may be sent to ymake, although it is usually not necessary to use this flag at all.

DESCRIPTION
ymake is used to generate Makefiles from a template, a set of cpp macro functions, and a per-directory input file called a yMakefile. This allows machine dependencies (such as compiler options, alternate command names, and special make rules) to be kept separate from the descriptions of the various items to be built. ymake is usually used from within the NCAR Graphics source distribution tree. When it is used in this way, it and all of the configuration files listed below can be found in the config subdirectory. ymake can also be used from the systems NCARG bin directory. When it is used in this way, it uses the NCARG_ROOT environment variable to find the configuration files in $(NCARG_ROOT)/lib/ncarg/config.

HOW IT WORKS
ymake invokes cpp with any -I or -D flags passed on the command line and passes it the following line:

	#include Template

The Template file reads in a machine-specific configuration file, a site-specific parameters file, a Project file defining variables, a file containing cpp macro functions for generating make rules, and the yMakefile in the current directory. Additionally, if the YMAKE_DEV_FILE environment variable is set to an existing file,ymake reads that file in directly after the Site file.

The yMakefile uses the macro functions to indicate what targets should be built; ymake takes care of generating the appropriate rules.

yMakefiles contain two types of macros, cpp macros and make macros. The cpp macros are interpreted by cpp when ymake is run. By convention they are mixed case. The make variables are written into the Makefile for later interpretation by make. By convention make variables are upper case.

The rules file (named Rules in the configuration directory) contains a variety of cpp macro functions that are configured according to the current platform. ymake replaces any occurrences of the charactor (]) with a newline to allow macros that generate more than one line of make rules. For example, the macro
	#ifndef	CleanFilesTarget
	#define	CleanFilesTarget(files)\
	]\
	clean::]\
		-@$(RM) files]
	#endif	/* CleanFilesTarget */
when called with CleanFilesTarget(foo foo1.o foo2.o) in the yMakefile will expand to
	clean::
		-@$(RM) foo foo1.o foo2.o
in the Makefile. To actually include the (]) charactor in a make rule, escape the (]) charactor by preceding it with the backslash (\) charactor.

On systems whose cpp reduces multiple tabs and spaces to a single space, ymake attempts to put back any necessary tabs (make is very picky about the difference between tabs and spaces). For this reason, colons (:), and equals (=) in command lines must be preceded by a backslash (\) to escape them. ymake assumes lines with colons (:) and equals (=) should not have a tab before them unless they are escaped.

USE IN NCAR GRAPHICS DISTRIBUTION
The NCARG distribution uses ymake extensively for builds within the source tree. It is also useful to build portions of the source tree or even external software, if it is used from the system's NCARG bin directory. As mentioned above, two special variables, TOPDIR and CURDIR, are set to make referencing files using relative path names easier. For example, the following command is generated automatically to build the Makefile in the directory ncarg2d/src/libncarg (relative to the top of the sources):

	%  ../../.././config/ymake -config ../../.././config \
		-DTOPDIR=../../../. -DCURDIR=./ncarg2d/src/libncarg

The config option to ymake is used to tell ymake that it is being invoked from within the NCAR Graphics full source tree. It should only be used by the Makefile.ini and Makefile files in the NCAR Graphics full source tree, or from the ymkmf program.

ymkmf can be used to create a Makefile in the NCAR Graphics full source tree. It generates the above ymake command.

USE OUTSIDE OF NCAR GRAPHICS DISTRIBUTION
When building programs outside the full source tree ymake should not be called directly. Instead the ymkmf command should be used. The typical way it would be used is to go to a directory in your source tree and then execute ``ymkmf topname''.

You would call it with the name of your top-level directory. For example if you had the ni source tree you could create the Makefile in the hlu sub-directory like this:

	host:~/src/ni/src/lib/hlu% ymkmf ni

The ymkmf script will search up the directory hierarachy until it finds the topdir that was passed to it. In this case it would create a Makefile with:

    TOP    =    ../../../.
    CURRENT_DIR    =    ./src/lib/hlu

The TOP and CURRENT_DIR symbols are used to keep a common include tree from the TOP directory.

Another feature of ymake that is provided to support using it outside of the NCARG distribution tree is "local" configuration files. If there is a file TOP/ymake.project, then it is included instead of the default Project file in the config directory. Also, if there is a file TOP/ymake.conf, then it is included directly before the $(YMAKE_DEV_FILE) described below.

Additionally, you can set the environment variable $(YMAKE_DEV_FILE) to an additional configuration file that you provide. The YMAKE_DEV_FILE gets included into the Makefile directly after the Site file so it can over-ride cpp symbols set in the Architecture file, or the Site file.

There are also some make symbols reserved for use in the YMAKE_DEV_FILE. They make it possible to configure the way programs are compiled and linked. For example, if you are working on some of the functions in libncarg_gks.a, then you would want your test programs to use your version of the libncarg_gks.a library, not the one in the system's lib directory. The way to do this would be to use the DEV_LIB_SEARCH make symbol described below:

    DEV_DEFINES
        This symbol is used to add additional "-D" flags to the compile line.

    DEV_INCLUDES
        This symbol is used to add additional "-I" flags to the compile line. These flags get added to the front of the compile line so they will take precedence over the other "-I" flags.

    DEV_LIB_SEARCH
        This symbol is used to add additional "-L" flags to the link line. These flags get added to the front of the link line so they will take precedence over the other "-L" flags.

    DEV_SYS_LIBS
        This symbol is used to add additional libraries to the link line, with "-l" flags. This symbol is often used in combination with the DEV_LIB_SEARCH symbol.

The DEV_LIB_SEARCH flag can be used to change the libncarg_gks.a file that gets linked as follows:

	DEV_LIB_SEARCH	=	-Lmy_dev_dir

INPUT FILES
Here is a summary of the files read by ymake.

Template		generic variables
	$Site	site-specific, FirstSite defined
	$Architecture	machine-specific
	$Site	site-specific, SecondSite defined
	$DevelopersFile	developers override file
	Project	NCARG-specific variables
	Rules	rules
	yMakefile	per-directory control file

The Template file determines which Architecture file needs to be included and includes all the other files. It also provides defaults for the generic variables.

The Site file is used to provide Site specific definitions.For example, this is the place the installer would set the install directories. That way, they use that same directory for all the architectures. Within the distribution, the Configure script sets up a Site.local file that will be used in place of the default Site file. If the installer wants different directories they can provide different values to the Configure script. Note that Site file gets included twice, once before the Architecture file and once after. Although most site customizations should be specified after the Architecture file, some, such as the choice of compiler, need to be specified before, because variable settings in the Architecture may depend on them. (There are currently no cases of this.)

The first time $Site file is included, the variable FirstSite is defined, and the second time, the variable SecondSite is defined. All code in Site should be inside a cpp conditional for one of these symbols.

The Architecture file sets Architecture specific cpp symbols. There is a separate Architecture file for each Machine/Operating System combination supported by ymake. These files should only set variables that are different from the defaults.

The DevelopersFile is a file specified by the YMAKE_DEV_FILE environment variable. This file is used to override the cpp symbols set in any of the above files for development purposes. The cpp symbols that are used to set the Optimization flags can also be set in this file. For example, the #define DEBUG line can go in this file, and all Makefiles created using it will use the debugging Optimization flags.

The Project file sets defaults for all the NCAR Graphics specific variables. For example this is where all the make symbols that point to specific libraries are set.

The Rules file contains all the cpp macros that are used in the yMakefiles.

NCAR GRAPHICS LIBRARY SYMBOLS
The following list of make symbols are defined by ymake in the Project file. These should be used in yMakefiles instead of specifying the file with a direct path name or "-l" flag. If you use the -local parameter to ymake these will not be defined.

    NCARGCLIB    libncarg_c.a
    NCARGLIB    libncarg.a
    NCARGGKSLIB    libncarg_gks.a
    NGMATHLIB    libngmath.a
    CGMLIB    libcgm.a
    NCARGRASLIB    libncarg_ras.a
    HLULIB    libhlu.a
    CTRANSLIB    libctrans.o
    ICTRANSLIB    libictrans.o
    ICTRANS_LIB    libictrans_.o

Additionally, the following symbols have been defined that combine the above make symbols into the groups they are usually used in:

    NCARGLIBS
        $(NCARGLIB) $(NCARGGKSLIB) $(NCARGCLIB)

    HLULIBS
        $(HLULIB)

There are also a full set of dependent library symbols to go along with the above symbols. These make symbols indicate the full path name of the library they represent. This is useful for putting the libraries on the dependency list of a link command. (See the FortranProgram and CProgram rules in the COMPILE/LINK RULES section.)

    DEPNCARGLOCLIB
    DEPNCARGCLIB
    DEPNCARGLIB
    DEPNCARGGKSLIB
    DEPNGMATHLIB
    DEPCGMLIB
    DEPNCARGRASLIB
    DEPHLULIB
    DEPCTRANSLIB
    DEPICTRANSLIB
    DEPICTRANS_LIB
    DEPNCARGLIBS
    DEPHLULIBS

COMPILE/LINK RULES
ymake has some basic rules that are used to compile executables.

ymake uses three make symbols to define the libraries to link with the object code in the current directory to create executables. These three symbols are:

    PROG_LIBS
        This symbol defines the libraries that are part of the current directory hierarchy. These libraries are linked in statically and they come before the "-L" flags on the link line.

    EXTRA_LIBS
        This symbol defines the libraries on the system that are not part of the current directory hierarchy, but that may not exist on all systems. These libraries must also be linked statically but they come after the "-L" flags on the link line.

    SYS_LIBS
        This symbol defines the system libraries that need to be linked into the executable. These libraries should be standard libraries on the system. They should be linked in dynamically so the executable has a better chance of running on multiple versions of the OS.

These make symbols are used with the following rules to create an executable. program indicates the name of the executable to create. objects indicates the object files that need to be linked to create the executable. deplibs indicate the libraries that the executable is dependent upon.

    FortranProgram(program,objects,deplibs)
        This rule creates a program by linking the listed objects with the libraries indicated by setting the $(PROG_LIBS), $(EXTRA_LIBS) and $(SYS_LIBS) make symbols. This rule also puts the install rule in. It installs the executable into the BIN_PATH defined in the Site file. The deplibs indicate a full path name to the libraries used in this link that should be put on the dependency line of the link rule. If the DEP[...] Library make symbols are used ymake will determine the path.

    FortranTarget(program,objects)
        This rule is essentially identical to FortranProgram except that it doesn't keep track of the dependent libraries, so it doesn't re-link if the libraries are re-compiled.

    FNotInstalledTarget(program,objects)
        This rule is essentially identical to FortranTarget except that it doesn't put the install rule in. It is intended to be used to create programs that are only used within the distribution or are installed into a different directory than the default BIN_PATH.

    CProgram(program,objects,deplibs)
        This rule is the same as FortranProgram except that it uses the C Compiler to link instead of the Fortran Compiler as the FortranProgram rule does.

    CTarget(program,objects)
        This rule is the same as FortranTarget except that it uses the C Compiler to link instead of the Fortran Compiler as the FortranTarget rule does.

    CNotInstalledTarget(program,objects)
        This rule is the same as the FNotInstalledTarget except that it uses the C Compiler to link instead of the Fortran Compiler as the FNotInstalledTarget rule does.

MANAGING SUBDIRECTORIES
ymake manages all subdirectory handling itself. It just needs to be told that the given directory has subdirectories, and what those subdirectories are. To do that, you use the #define IHaveSubdirs cpp directive and set the make symbol SUBDIRS to the list of subdirectories in the yMakefile. If a subdirectory listed in the SUBDIRS symbol doesn't exist, then ymake reports it and continues. That way, it is possible to be working with portions of a build tree without having to edit the yMakefiles.

MAKE SYMBOLS
The following is a list of many of the make symbols that are reserved for use in yMakefiles:

    EXTRA_CDEFINES
        Used as part of CFLAGS to compile C programs. It should be used to put in additional -D flags for the compile line.

    EXTRA_FDEFINES
        Used as part of FFLAGS to compile Fortran programs. It should be used to put in -D flags for the compile line. Be careful since the -D flag is not supported for all Fortran compilers.

    EXTRA_DEFINES
        Used to add -D flags to both fortran and C compiles. Same warning applies for Fortran compiles.

    EXTRA_INCLUDES
        Used to add -I flags to C compiles.

    EXTRA_CLDFLAGS
        Used to add additional LD flags for the linking of C programs.

    EXTRA_FLDFLAGS
        Used to add additional LD flags for the linking of Fortran programs.

    EXTRA_LDFLAGS
        Used to add additional LD flags for the linking of Fortran and C programs.

    PROG_LIBS
        Used to specify the libraries that need to be linked into a program that are part of the distribution. Only make symbols should be used to set this make symbol. ex. PROG_LIBS = $(NCARGLIB) $(NCARGLOCLIB)

    EXTRA_LIBS
        Used to specify the libraries that need to be linked into a program that are not part of the distribution, but that may not be installed on all systems - so they need to be linked into the executable statically for the architectures that support dynamic libs.

    SYS_LIBS
        Used to specify the system libraries that need to be linked into a program. These libraries include the libc.a and all other libraries that are sure to be installed on the target system. These should be linked dynamically so our programs work no matter which version of the OS is being used on the target system.

    SUBDIRS
        Used in conjunction with the IHaveSubdirs cpp symbol to manage sub-directories. It should be set to the list of sub-directories that should be built.

SYSTEM SPECIFIC SYMBOLS
For each supported system, there will be a set of cpp symbols defined in ymake that can be used in the yMakefile to conditionally set things in that ymakefile. There are six possible symbols that can be set:

    Os  Name of Operating system

    MajorOs
        Major Version Number/Designator

    MinorOs
        Minor Version Number/Designator

    SubMinorOs
        SubMinor Version Number/Designator

    Vendor
        Vendor Name

    Architecture
        Architecture Name, possibly including Model number.

This table shows the actual symbols that are defined, or the values the given symbols are defined to, for the currently supported systems:

VENDOR	HP	IBM	SUN	SUN	CRAY	SGI	DEC	DEC
ARCH	HP9k7xx	RS6kxx	sun[34]	sun4	YMP	IPxx	RISC	alpha
OS	HPUX	AIX	SunOS	Solaris	UNICOS	IRIX	ULTRIX	OSF1
MAJOR=	A	3	4,5	5	6	4	4	1
MINOR=	09	1	1,?	?	1	0	3	1
SUBMINOR=	01	null	2,3,?	?	null	5[C-F]	null	null

If you want to have any of these symbols defined in the source code you can set the EXTRA_DEFINES symbol described above to the following make symbols that are defined by the Template:

    VENDOR_DEF
        This make symbol is set to -Dsym where sym is the Vendor name listed above for the given system.

    ARCH_DEF
        This make symbol is set to -Dsym where sym is the Architecture name as listed above for the given system.

    OS_DEF
        This make symbol is set to -Dsym where sym is the Os name as listed above for the given system.

    MAJOR_DEF
        This make symbol is set to -DMAJOR=n where n is the major revision designator for the given system.

    MINOR_DEF
        This make symbol is set to -DMINOR=n where n is the minor revision designator for the given system.

    SUBMINOR_DEF
        This make symbol is set to -DSUBMINOR=n where n is the sub-minor revision designator for the given system. If it is null above, then SUBMINOR_DEF will also be null.

ENVIRONMENT VARIABLES
The following environment variables may be used by ymake.

    YMAKE_DEV_FILE
        If defined, this should be a valid file including make symbol definitions to override the default ones. This Environment variable is only used if ymake is being used from the bin directory; it will not affect a full NCAR Graphics distribution build.

    NCARG_ROOT
        This is used by ymake to find its config directory if ymake is being used from the system's bin directory.

    NCARG_CONFIG
        This is used by ymake to find its config directory if ymake is being used from the system's bin directory. It is more specific, thus more binding than the NCARG_ROOT environment variable.

SEE ALSO
make(1),ncargpath(1)

BUGS
ymake isn't particularly easy to use.

COPYRIGHT
Copyright 1987, 1988, 1989, 1991, 1993 University Corporation for Atmospheric Research
All Rights Reserved