6.3.1 Building libraries with Mmake

Generally Mmake will do most of the work of building libraries automatically. Here is a sample Mmakefile for creating a library.

MAIN_TARGET = libmypackage
depend: mypackage.depend

The Mmake target ‘libfoo’ is a builtin target for creating a library whose top-level module is ‘foo.m’. The automatically generated Mmake rules for the target ‘libfoo’ will create all the files needed to use the library. (You will need to run ‘mmake foo.depend’ first to generate the module dependency information.)

Mmake will create static (non-shared) object libraries and, on most platforms, shared object libraries; however, we do not yet support the creation of dynamic link libraries (DLLs) on Windows. Static libraries are created using the standard tools ar and ranlib. Shared libraries are created using the ‘--make-shared-lib’ option to ‘ml’. The automatically generated Make rules for ‘libmypackage’ will look something like this:

libmypackage: libmypackage.a libmypackage.so \
                $(mypackage.ints) $(mypackage.int3s) \
                $(mypackage.opts) $(mypackage.trans_opts) mypackage.init

libmypackage.a: $(mypackage.os)
        rm -f libmypackage.a
        $(AR) $(ARFLAGS) libmypackage.a $(mypackage.os) $(MLOBJS)
        $(RANLIB) $(RANLIBFLAGS) mypackage.a

libmypackage.so: $(mypackage.pic_os)
        $(ML) $(MLFLAGS) --make-shared-lib -o libmypackage.so \
                $(mypackage.pic_os) $(MLPICOBJS) $(MLLIBS)

libmypackage.init:
        …

clean:
        rm -f libmypackage.a libmypackage.so

If necessary, you can override the default definitions of the variables such as ‘ML’, ‘MLFLAGS’, ‘MLPICOBJS’, and ‘MLLIBS’ to customize the way shared libraries are built. Similarly ‘AR’, ‘ARFLAGS’, ‘MLOBJS’, ‘RANLIB’, and ‘RANLIBFLAGS’ control the way static libraries are built. (The ‘MLOBJS’ variable is supposed to contain a list of additional object files to link into the library, while the ‘MLLIBS’ variable should contain a list of ‘-l’ options naming other libraries used by this library. ‘MLPICOBJS’ is described below.)

Note that to use a library, as well as the shared or static object library, you also need the interface files. That is why the ‘libmypackage’ target builds ‘$(mypackage.ints)’ and ‘$(mypackage.int3s)’. If the people using the library are going to use intermodule optimization, you will also need the intermodule optimization interfaces. The ‘libmypackage’ target will build ‘$(mypackage.opts)’ if ‘--intermodule-optimization’ is specified in your ‘MCFLAGS’ variable (this is recommended). Similarly, if the people using the library are going to use transitive intermodule optimization, you will also need the transitive intermodule optimization interfaces (‘$(mypackage.trans_opt)’). These will be built if ‘--trans-intermod-opt’ is specified in your ‘MCFLAGS’ variable.

In addition, with certain compilation grades, programs will need to execute some startup code to initialize the library; the ‘mypackage.init’ file contains information about initialization code for the library. The ‘libmypackage’ target will build this file.

On some platforms, shared objects must be created using position independent code (PIC), which requires passing some special options to the C compiler. On these platforms, Mmake will create .pic_o files, and ‘$(mypackage.pic_os)’ will contain a list of the .pic_o files for the library whose top-level module is ‘mypackage’. In addition, ‘$(MLPICOBJS)’ will be set to ‘$MLOBJS’ with all occurrences of ‘.o’ replaced with ‘.pic_o’. On other platforms, position independent code is the default, so ‘$(mypackage.pic_os)’ will just be the same as ‘$(mypackage.os)’, which contains a list of the .o files for that module, and ‘$(MLPICOBJS)’ will be the same as ‘$(MLOBJS)’.