BUILD
Jump to navigation
Jump to search
Builds an NeXtMidas command or library
<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