Creating and using a JSOC library
This note describes how to compile and link to a JSOC library using "make".
The make utility uses several makefiles to generate JSOC libraries. The main makefile used in this process is $JSOCROOT/make_lib.mk. It contains most of the general rules for making C files (from .pgc files), object files, executables, and, in particular, libraries (see http://jsoc.stanford.edu/trac/wiki/DrmsMakeModule for a sample Makefile that specifies rules for generating modules). These rules are made general by including parameters in their definitions:
LIBFILE := $(LIBDIR)/lib$(LIBNAME).a ... # Rule for creating library file. $(LIBFILE): $(PLATOBJ) $(MAKELIB) $(LIBFILE) $(PLATOBJ) ln -sf ../../$(RELDIR)/$(LIBFILE) $(MKROOT)/lib/$(PLAT)/
Variables like $LIBNAME are not specified in make_lib.mk. Instead, they are specified in other makefiles, named “Makefile”, which then include make_lib.mk. The result is a rule for creating a library that is tailored to the particular Makefile including make_lib.mk.
To use the library “libastro” as an example, the Makefile in $JSOCROOT/src/pipeline/libraries/libastro contains these key lines:
LIBNAME = astro ... include $(MKROOT)/make_lib.mk
As a result, when make runs on $JSOCROOT/src/pipeline/libraries/libastro/Makefile, it has a rule available for creating the library named libastro.
Each subdirctory in $JSOCROOT that has C files that are used to make libraries has such a Makefile. Running make from the root directory, $JSOCROOT, causes the make utility to run recursively on all subdirectories (provided that the Makefiles in the parent directories appropriately name the subdirectories contained by the parents – see “Standard JSOC makefile entries” in the sample Makefile below). make_lib.mk contains the instructions for recursively calling make on subdirectories.
The following is a template Makefile used to generate a library.
##### Makefile for JSOC library ##### # Run $JSOCROOT/configure before using this makefile # for the first time on a machine. # The next line refers to $JSOCROOT/make.mk include ../../make.mk # Running “make” with no arguments from the directory containing this # makefile will build the library listed in the “LIBNAME” below # from the object modules listed in “OBJ” below. This # makefile and the source files needed to generate the .o files are the # only files required to be present in the directory containing this makefile ##### Library Targets ##### # The following line lists all the .o files whose code will be placed in the # library. Replace the fileX with the actual file names. OBJ = file1.o file2.o ... fileN.o # The following line lists the name of the library to create. # $JSOCROOT/make_lib.mk will create the library lib/<plat>/libnameOfLIb.a. # Replace nameOfLib with the actual library name. LIBNAME = nameOfLib # If this makefile resides in a directory that contains subdirectories # that contain makefiles, then uncomment the following line, replacing # the subDirX with the actual directory names. # SUBDIR := subDir1 subDir2 ... subDirN ##### Standard JSOC makefile entries ##### # Standard library make rules include $(MKROOT)/make_lib.mk # Cleanup rules include $(MKROOT)/make_clean.mk # Directory-specific configure rule: configure: .PHONY: configure # Automatically generated dependencies -include make_dep.mk
This Makefile simply generates the library. In order for an executable to use this library, the executable's source must #include the library's header file. The platform-specific makefile (i.e., make.linux_ia32, make.linux_ia64, or make.linux_x86_64) defines the IPATH make variable to include $JSOCROOT/include. And the $JSOCROOT/configure script will create links from $JSOCROOT/include to the actual header file. So all you need to do is to directly include the header file into your source, and the complier will know where to locate it.
In addition, the executable must be linked against the library. There are many ways to specify this linkage. For example, you can either add the library to one of the library definition variables in $JSOCROOT/make_lib.mk (i.e., SERVERLIBS, EXELIBS, MODLIBS), or add a line to the executable's Makefile (e.g., LIBS := -lastro $(LIBS)). The best way depends on how general the library will be. If it is something used widely by modules, then adding “-llibname” to MODLIBS may be the best solution. If it will have a more restricted applicability, then modifying the LIBS make variable in Makefile may be more appropriate. NOTE: The final order of the libraries specified in the compiler's link command matters. If library A refers to library B, then library A must precede library B in this order. Finally, make will know where to locate the library. The platform-specific makefiles define the LPATH make variable to include $JSOCROOT/lib/$PLAT. And the general library make rule in $JSOCROOT/make_lib.mk will make a link from $JSOCROOT/lib/$PLAT to the actual library.