makeutil

Topics covered in this chapter:

Introduction

This package provides a set of routines to ease the writing of makefiles for Mosel projects. Typically named make.mos, a makefile is a program that builds and combines the components of a project. For instance, the makefile for this package that is generated from the source file makeutil.mos looks like the following:

 model make_makeutil
 uses 'makeutil'
  mos2bim("makeutil.mos","makeutil.bim")
 end-model

Executing this Mosel program (i.e. invoking the command mosel make) will produce the package makeutil.bim.

A make.mos program supports at least two parameters:

• MODE is the execution mode; by default this is 'release', and with 'debug' the corresponding compilation options are selected, that is, using the Mosel program above with the command mosel make MODE=debug you are generating the debug version of this package.
• TODO indicates the target to process: by default this will be 'all', another typical target is 'clean' to remove all created elements: to clean up any generated files for this package, use the command mosel make TODO=clean

Default behaviour and usage examples

Most operations of makeutil will cause the program to terminate (with an error code) in case of failure. Build operations are performed only if the source or dependencies are newer than what was previously built. When the target is 'clean', each routine automatically deletes the files it has generated before.

Logging output

The routines of this package produce logging output to show in detail which actions have been carried out. For example, if we extend the simple package makefile from the previous section with a parameter for the destination directory, such as:

 model make
 uses 'makeutil'

 parameters
   BUILDDIR='build'             ! Destination directory
 end-parameters

 mos2bim('mypackage.mos',BUILDDIR+'/dso/mypackage.bim')

 end-model

then we can expect to see the following output from running the command mosel make:

 -> MKPATH build/dso
 -> mosel comp -o build/dso/mypackage.bim mypackage.mos

To be noted:

• The destination directories are automatically created.
• Recompilation will occur only if 'mypackage.mos' is modified.

A subsequent call to the command mosel make TODO=clean will result in this logging output:

 -> RM build/dso/mypackage.bim
 -> RMDIR build/dso
 -> RMDIR build

To be noted:

• There is no need for any explicit deletion procedure for basic tasks.
• Empty directories are automatically deleted.

Compilation of C code

The Mosel module math is generated from 2 source files math.c and bigint.c and it has a public header file mmath.h (see the Mosel Open Source Repository). The Mosel makefile for building this module shown below introduces some additional functionality of makeutil, namely the file copy with cp and the setting of specific compilation options via LIBS—compiling C code will require a C compiler to be available:

 model make
 uses 'makeutil'

 parameters
   BUILDDIR='build'             ! Destination directory
 end-parameters

 LIBS('posix')+=['m']           ! On Posix systems the math library is required
 c2dso(['math.c','bigint.c'],BUILDDIR+'/dso/math.dso')
 cp('mmath.h',BUILDDIR+'/include/mmath.h')

 end-model

It produces this logging output on a Linux machine:

 -> cc -fPIC -Wall -fvisibility=hidden -O2 -DNDEBUG -I "/opt/xpressmp/include"
-c math.c -o math.o
 -> MKPATH build/dso
 -> cc -fPIC -Wall -fvisibility=hidden -shared math.o -o build/dso/math.dso
-L "/opt/xpressmp/lib" -lm
 -> MKPATH build/include
 -> CP mmath.h build/include/mmath.h

And on a Windows platform we can expect to see the following log:

 -> cl -nologo -W2 -GS- -MD  -D_CRT_SECURE_NO_WARNINGS -O2 -DNDEBUG
"-IC:\xpressmp\include" -c math.c -Fomath.obj
 -> MKPATH build/dso
 -> cl -nologo -W2 -GS- -MD  -D_CRT_SECURE_NO_WARNINGS -LD math.obj
-Febuild/dso/math.dso -link -IMPLIB:math.lib -incremental:no -subsystem:console,"5.02"
   Creating library math.lib and object math.exp
 -> MKPATH build/include
 -> CP mmath.h build/include/mmath.h

The matching command mosel make TODO=clean will result in this output when performed on Windows:

 -> RM math.obj
 -> RM build/dso/math.dso
 -> RMDIR build/dso
 -> RM math.exp
 -> RM math.lib
 -> RM build/include/mmath.h
 -> RMDIR build/include
 -> RMDIR build

To be noted:

• Typical compilation options are setup by default.
• The paths to Xpress (include and libraries) are also setup.
• Developers have the possibility to add system-specific options.
• Recompilation will occur only if 'math.c' or 'bigint.c' are modified.
• The copying of the header file 'mmath.h' will happen only if the source has changed.

Building Insight apps

The makefile included with the Mosel Insight app from the 'Getting Started' Manual (see subdirectory examples/getting_started/Mosel/folioinsightxml of the Xpress installation or the online examples database) uses the zip subroutine provided by makeutil:

 model "Insight App Build - Folio"
 uses 'makeutil'

 parameters
   APPNAME="folioinsightxml"
 end-parameters

 mos2bim(APPNAME,"..")
 zip("../"+APPNAME+".zip", "..", APPNAME+".bim", APPNAME+".xml",
    "source/"+APPNAME+".mos", "model_resources", "client_resources")

end-model

Calling mosel make will result in this logging output.

 -> mosel comp -o ..\folioinsightxml.bim folioinsightxml
 -> ZIP ../folioinsightxml.zip .. folioinsightxml.bim folioinsightxml.xml
source/folioinsightxml.mos model_resources client_resources

To be noted:

• The zip and tar subroutines of makeutil support specification of a list of files (optionally with wildcards) and directories.

To delete the generated files, simply use the command mosel make TODO=clean as with all preceding examples.

Runtime parameters

MODE  : string

Define the running mode of the makefile.
Default value	'release'
Notes	1. Predefined modes provided by this package are release, debug, doc, clean. A specific makefile may define additional modes. 2. This parameter is used to initialise the variable runmode.

NOASSERT  : boolean

Decides whether to keep assertions in debug mode.
Default value	false
Note	If true and debug mode is enabled, assertions will not be kept (they are removed in release mode).

TODO  : string

Specifies which operation to execute.
Default value	'all'
Values	"all" Build all components in release mode. "debug" Build all components in debug mode. "doc" Build all components, option -D is used to compile Mosel files. "clean" Delete generated files.
Note	This parameter is used to initialise the variable runmode when MODE is not specified.

Constants

USE_CC  = 1

Use CC for linking ( obj2exe, obj2dso)

USE_CXX  = 2

Use CXX for linking ( obj2exe, obj2dso)

all_oses  = {'winnt','macos','linux'}

Supported operating systems

all_procs  = {'x86','arm'}

Supported processors

Variables

ARCH  : integer

Current architecture (32 or 64).

CC  : string

C compiler.
Note	Automatically initialised from the environment variable CC (default: 'cl' on Windows and 'cc' on Posix).

CFLAGS  : dynamic array(systems) of string

C compiler flags depending on the system.
Note	A default value for each supported system is automatically assigned to CFLAGS(os) (with os in all_oses). The value of the environment variable CFLAGS is assigned to the label of the running host ( e.g. CFLAGS("linux-x86_64")).

CXX  : string

C++ compiler.
Note	Automatically initialised from the environment variable CXX (default: 'cl' on Windows and 'c++' on Posix).

CXXFLAGS  : dynamic array(systems) of string

C++ compiler flags depending on the system.
Note	A default value for each supported system is automatically assigned to CXXFLAGS(os) (with os in all_oses). The value of the environment variable CXXFLAGS is assigned to the label of the running host ( e.g. CXXFLAGS("winnt-x86_32")).

DYLFLAGS  : dynamic array(systems) of string

Flags for building modules (dynamic libraries) depending on the system.
Note	A default value for each supported system is automatically assigned to DYLFLAGS(os) (with os in all_oses).

EXE  : string

Current extension for executables (operating system dependent, either ".exe" or "").

INCDIRS  : dynamic array(systems) of list of string

List of search paths for header files depending on the system.
Note	INCDIRS("all") is automatically initialised according to the location of the Xpress header files (based on the environment variable XPRESSDIR or the location of the instance of Mosel running the program).

LDFLAGS  : dynamic array(systems) of string

Linker flags depending on the system.
Note	The value of the environment variable LDFLAGS is assigned to the label of the running host ( e.g. LDFLAGS("macos-arm_64")).

LIBDIRS  : dynamic array(systems) of list of string

List of search paths for libraries depending on the system.
Note	LIBDIRS("all") is automatically initialised according to the location of the Xpress libraries (based on the environment variable XPRESSDIR or the location of the instance of Mosel running the program).

LIBS  : dynamic array(systems) of list of string

List of additional libraries depending on the system.

MFLAGS  : string

Mosel compiler flags.
Note	Flags for debugging and generating documentation are automatically selected depending on runmode. This setting might be used for defining additional flags.

MOSEL  : string

The mosel command.
Note	The default value is "mosel" unless the command cannot be found in the current PATH environment. In this case the command running the makefile will be used.

MOSELDIR  : string

Installation directory of Mosel.

Notes

1. The default value is taken from the environment variable MOSELDIR, or (if not defined) from XPRESSDIR. If the specified path is not a directory, the value will be deduced from the command running the makefile. 2. The default value is "*", it will be redefined from the location of the command running the makefile. 3. The path MOSELDIR/include is automatically added to the include paths for the compilation of C/C++ programs. 4. The path MOSELDIR/lib is automatically added to the library paths for the compilation of C/C++ programs.

OBJ  : string

Current extension for object files (operating system dependent, either ".obj" or ".o").

OS  : string

Current operating system (from all_oses).

PROC  : string

Current processor (from all_procs).

WLFLAGS  : string

Linker flags for Windows.

errfid  : integer

File ID of the error stream.
Note	All error messages are directed to this stream. The default value is getfid(F_ERROR).

exitonfail  : boolean

Decides whether program terminates after an error.
Values	true The program terminates after an error occurred during execution of a command. false The program is not terminated after an error and getsysstat should be used to check the error status.
Note	By default this setting is true.

iswindows  : boolean

true if the running system is Windows.

runmode  : string

Execution mode for makefile.
Values	"release" Compile for release with optimization. "debug" Compile with debugging information. "doc" Compile for release, including documentation for Mosel files. "clean" Delete generated files.
Notes	1. This variable controls the behaviour of most routines of this package: with debug or doc the compilation parameters are selected to produce respectively debugging information or documentation. When the value "clean" is selected, the target file(s) of a routine will be removed (if present). If any directories are created by the build process and they are empty after removing all generated files, then these directories will equally be deleted. 2. The default value of the execution mode depends on the parameters TODO and MODE.

systems  : set of string

All system combinations.
Note	In addition to all possible combinations of operating system, processor, and architecutre ( e.g. "linux", "linux-x86", "linux-x86_32", "linux-x86_64", ...) this set also includes "all" and "posix" ( i.e. all except Windows).

Subroutines