ConvertBot: Builds an NeXtMidas command or library

2020-04-27T22:05:09Z

Builds an NeXtMidas command or library

New page

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]]

BUILD - Revision history

ConvertBot: Builds an NeXtMidas command or library