View source for BUILD

Builds an NeXtMidas command or library
<pre>
<NAME>  Name of the command/library (or "ALL", or a '|' separated list of files
        in the same area)
<AREA>  Area of the option tree containing file (or "ALL")
<OPT>   Option tree containing file [DEFAULT=SYS]

This command is used to compile a command or library under the NeXtMidas
framework. It looks for .java, .c, .clib, .cpplib, or .flib extensions and
compiles the routines found using the appropriate compiler.

If AREA="ALL" or "*" then all of the following areas will be included in the
build (since 3.1.2: this list is read from the build.codeareas.libs and
build.codeareas.other properties in the build.props file):
    inc,lib,libg,libm,net,  intr,prim,host,test,mcr

For .java, .c, .clib .cpplib, and .flib files, the name "ALL" or "*" can be used
to compile all of the routines found in the specified <AREA>. Note that if using
XBC to compile host primitives "ALL" will not include those host primitives not
in the commands.cnf file (this is done for compatibility with X-Midas).

If only <NAME> is specified then the command with the given name will be built.
This provided a quick way to rebuild a primitive that has been modified.

The build.props File
--------------------
  Default definitions for compiler defaults used by BUILD can be found in
  $NMROOT/nxm/sys/cfg/build.props. This file is defined as a normal Java
  properties file and contains values for specific compiler options for each of
  the supported environments. Additional properties can be added either to this
  file (to change build behavior for SYS) or to <OPT>/cfg/build.props. Property
  values defined in an option_tree build.props will override the defaults in SYS
  (this is the preferred way of changing the flags used for a given option
  tree).

  The .append operator can also be used to add any existing properties
  definitions (since NeXtMidas 2.9.2). A properties file in
  <OPT>/cfg/build.props containing:

      cflags.UNIX.append      = -DFOO

  will append the "-DFOO" compiler definition to the existing Unix CFLAGS
  (cflags.UNIX) compiler flags, but before the native.UNIX.cflags property.

  The .append.<machine_arch>bit (e.g. .append.32bit or .append.64bit) operator
  allows additional flags to be added for 32-bit or 64-bit machines. E.g.

      ifort.comp.append.32bit = -i-static

  will append the "i-static" Intel compiler flag only on 32-bit machines for the
  "ifort.comp" property (i.e. the Intel Fortran compiler and flags).

  The .prepend operator can also be used to prepend any existing properties
  definitions (since NeXtMidas 2.9.2). This is useful to override the default
  native libraries to link against (since the linkers link libraries in the
  order they are specified on the command line).

  The fflags.host property in build.props can be used by an option tree's
  build.props to provide additional compile and link flags to for their Fortran
  HOST primitives (when using XBC).

  Reminder: When you use -l<libname> the linker looks for lib<libname>.[a|so].
  The linker searches and processes libraries and object files in the order they
  are specified.

Building Native Code
--------------------
  Classes with native components (e.g. NTerminal.java, NTerminal.c in SYS) are
  automatically compiled and linked into a shared object library by the name
  <NAME>_<ostag><osarch>.<so|dll> to be loaded by the java class when
  instantiated. The <ostag> is "lin" for Linux, "win" for Windows, etc. (view
  the build.props file for a more complete list of these tags). The <osarch> is
  32 for 32-bit and 64 for 64-bit systems. The addition of the OS tag and
  <osarch> are intended to allow versions of the libraries for different
  platforms to coexist on a shared drive. Some examples: "Native_lin32.so,
  Native_lin64.so, Native_win64.dll, NTerminal_sol32.so"

  The linker stage also automatically looks for a
  lib<NAME>_<ostag><osarch>.<so|a|dll> or a libAll_<ostag><osarch>.<so|a|dll>
  and adds them to the linker stage if found.
  These libraries are typically created by an option tree specific buildopt.mm
  macro or through the use of a .clib, .cpplib, or .flib file (see below).

Building Native Libraries Using .clib, .cpplib, and .flib (.[c|cpp|f]lib) Files
-------------------------------------------------------------------------------
  This feature allows easy creation of shared object libraries without the need
  for a complicated build script or Makefile (since NeXtMidas 2.1.1).
  The .[c|cpp|f]lib file simply list the names of the native files to be
  included in the library. A typical file will look similar to this:

    # Defines the files included in the libMyLib library,
    # files are listed one-per-line.
    file1.c
    file2.c
    preCompiled.a

  Any blank lines or lines that start with a pound sign ('#') are treated as
  comments and ignored. All other lines are expected to list each of the
  component files one-pre-line. Files with a typical source code
  extension (e.g. ".c", ".for") are compiled automatically before linking them
  into the shared object. Any other files (e.g. ".a") are assumed to be pre-
  compiled libraries that will be linked in. The resulting shared object will
  be named <fname>_<ostag><osarch>.<so|dll> where <fname> matches the name of
  the .[c|cpp|f]lib file.

  Wildcards (* and ?) are supported for the files in the .[c|cpp|f]lib file.
  The * (star) wildcard is use to match any character zero or more times.
  The ? (question mark) wildcard is use to match any character exactly one time.
  Files with sub-directories (e.g. mylib/xyzlib.c, mylib/*.for) and even files
  with relative references to sibling directories (e.g. ../lib/abc*.c)

  Absolute paths to files are supported (e.g. /path/to/alib/mystaticlib.a) and
  BETA support for references to other .[c|cpp|f]lib files was also added
  (e.g. libxyz.flib) (since NeXtMidas 2.7.0).

  The difference between .clib, .cpplib and .flib files is that the C compiler
  is used to link .clib files, the C++ compiler is used to link the .cpplib
  files, and the Fortran compiler is used to link .flib files.
  The .flib files are only intended for use with XBC.

  Warning: For static libraries (*.a), only functions that are referenced in
  your listed files will be included into the shared object by the linker. One
  trick to get the necessary functions into your shared object is to have a
  dummy module (e.g. refs_to_funcs_in_staticlib.c) that calls all the functions
  from the static libraries and include that in your .[c|cpp|f]lib file.

The <opt>/cfg/primitives.cfg File (BETA)
----------------------------------------
  Support for the primitives.cfg file in the cfg area of an option tree for host
  primitives (i.e. X-Midas style build configuration) (since NeXtMidas 2.7.0).
  The <opt>/cfg/libraries.cfg is also parsed (BUT NOT BUILT) to resolve all the
  library names for the specified option tree (via the libdepend directive). All
  valid primitives.cfg and libraries.cfg directives and conditionals are parsed.

  Here are the valid directives and their description:
    cflags       - Compile flags for the compiler.
    comment line - Lines starting with a "!" character are ignored
    conditionals - Targets or directives intended to build conditionally based
                   on the current OSNAME or OSTYPE using the "->" arrow syntax.
                   Can also use "NEXTMIDAS" as a conditional value.
                   Can also use existences of OS environment variables as a
                   conditional (since NeXtMidas 3.1.2).
    lflags       - Link flags for linker.
    libdepend    - Libraries from other option trees to link the target against.
    headers      - Associates header files with a particular target.
                   This does not effect build. For documentation only.
    optdepend    - (primitives.cfg only) Indicates what the PATH should be when
                   CONVERT MSGCFG2INC generates the configured messages
                   C/C++/Fortran include files.
                   This does not effect build. For documentation only.
    libname      - (libraries.cfg only) parsed but ignored
    modules      - Associates code files with a particular target.
                   (parsed BUT NOT supported yet)
    <targets>    - host primitive or library target

  Directives that are not indented below a <target> are considered global to all
  targets that follow them.

  See $NMROOT/nxm/sys/hlp/using_libraries.doc for a copy of X-Midas's docs for
  a detailed description, syntax, and examples usages of primitives.cfg and
  libraries.cfg (NOT SUPPORTED yet).

  Note: OS environment variables (preceded with '$') are automatically
        expanded in the following directives: cflags, lflags and libdepend for
        third party libraries (since NeXtMidas 3.1.2).

Things to Note
--------------
  - The /DEBUG flag will show numerous messages about the compile arguments used
    which might be helpful in debugging any potential problems.

  - By default the nm shell will be restarted at the end of a compilation to
    ensure that the new classes are reloaded correctly. To prevent this
    (especially inside a macro) use the /NOEXIT flag.

  - When building with XBC support (support for host primitives in Fortran/C++)
    the XBC option tree must be on the path. BUILD will automatically check for
    the XM_FORTRAN or NM_FORTRAN environment variable to specify the Fortran
    compiler to use. Please read the "XBC" section in the "NeXtMidas User's
    Guide" for more details.

    The NM_CC and NM_CXX environment variables can be used to override the
    configured C or C++ compilers specified in build.props, respectively
    (since NeXtMidas 2.9.2). E.g. to use Intel's icc over gcc and g++ without
    having to update build.props, setenv NM_CC icc and setenv NM_CXX icc.

    The NM_CC_OPTIONS and NM_CXX_OPTIONS environment variables can also be used
    to add additional C or C++ compiler flags/options to append to end of
    compile flags, respectively (since NeXtMidas 2.9.2).

    WARNING: Native (C, C++, Fortran) libraries (*.so for dynamic or *.a static)
    built in X-Midas and/or other versions of NeXtMidas SHOULD NOT be mixed and
    matched and/or linked into your library or host primitive(s). Doing so will
    result in random segmentation faults or errors. The reason for this
    is that different version of X-Midas and NeXtMidas have different link level
    API binding that are not necessarily compatible. Your code may seem to work
    on occasions but don't count on it working in a production environment.
    Be careful NOT mix and match these libraries, e.g. adding
    -l<name_of_xm_built_lib> link flags or including anXmidasBuiltlib.[a|so]
    in your .[c|cpp|f]lib. Independent libraries without any X-Midas/NeXtMidas
    dependency are normally safe to link against via the -l<libnam> link flag
    or in a .[c|cpp|f]lib file.

  - Users who are building files that are on a shared NFS mount will need to
    verify file permissions before and after the build. NeXtMidas will always
    use the file system's default file visibility flags for files it creates.
    Those flags may or may not match the ones required for other users to read
    (or write, in the case of developers) the files.

Examples:
  1. Build the class $NMROOT/nxm/sys/lib/DataOp.java:
        nM> build DataOp lib

  2. Build the classes Layer1D and Layer2D in the LIBG area of SYS:
        nM> build Layer1D|Layer2D libg sys

  3. Build all of the primitives in the ICE option tree:
        nM> build all prim ice

  4. Build the class $NMROOT/nxm/sys/libg/MPlot.java:
        nM> build MPlot libg sys

  5. Show all the compile time flags and other information to track the
      build process (useful for debugging build issues):
        nM> build/debug NTerminal lib

  6. Build an area not in the default list of those automatically built:
        nM> build all myarea myoption

  7. Build all of the files in the LIB area of MYOPT but include some extra
      compiler flags when building any C libraries and turning on XLint warning.
        nM> results FLAGS {CFLAGS_UNIX="-DHEADLESS -DNOSPECIAL -Wall",&
                           LFLAGS_UNIX="-I/home/smith/clibs",&
                           JAVA_FLAGS="-Xlint -Xlint:-rawtypes"}
        nM> build/BLDFLAGS=^FLAGS/keep * lib myopt

  8. Build all the files, in all areas of the DSP option tree:
        nM> build all all dsp

  9. Build nxm.sys.test.junit.lib.FileUtilTest.java unit test:
        nM> build FileUtilTest test/junit/lib sys
     -OR-
        nM> build junit/lib/FileUtilTest.java test sys

  10. Build just the native (C/C++) files for SYS:
        nM> build/bldtypes=native * * sys

Switches:
  /BLDFLAGS=  - Extra build flags to use. This is a table of values matching
                the names in build.props (except the names in the table use '_'
                in place of '.' and are in upper case) where the values are
                extra compiler/linker options to prepend to the build.props
                value. (Since 2.1.0).
  /BLDTYPES=  - Types of files to build (Java,Native,Host). Takes precedence
                over /DOHOST and /DONATIVE. (Since 3.3.1) [DEF=ALL]
  /COUNT=<res> - INTERNAL USE ONLY: Store a count of the number of files
                explicitly built/compiled. A negative count generally means
                there is an error.                                 (Since 3.3.1)
  /DEBUG      - Turn on debugging.
  /DOGENERATE - Generate new system math libraries. [DEF=TRUE]
  /DOHOST     - Compiles the host (C++/Fortran) files [DEF=FALSE, TRUE when XBC
                is in PATH or when <AREA>=HOST].
                Note: /DOHOST and /DONATIVE should usually be used together.
  /DONATIVE   - Compiles the native (C/C++) files. [DEF=TRUE]
  /KEEP       - Keep intermediate files when building. Keeps the function
                prototypes nxm_<opt>_<area>.h, .o files
  /NOEXIT     - Prevent class reloading via shell restart. [DEF=TRUE in macro,
                FALSE at command prompt]
  /WARN=OFF   - Suppress warning messages (e.g. when there are no java/native
                source files to build). (Since 3.3.0). [DEF=TRUE]

See Also: MAKE, BUILDOPT, BLD

</pre>

[[Category:NXM_Explain]]