Building a Library
1. All code - libraries and programs using those libraries - resides under a single directory.
That location is defined with an environment variable, TOT. E.g. if that directory is /home/code, and you're using a tcsh shell, do: setenv TOT /home/code 2. All helper Makefiles reside under a single directory. That location is defined with an environment variable, MAKEFILES_DIR. E.g. if that directory is /home/code/makefiles, and you're using a tcsh shell, do: setenv MAKEFILES_DIR /home/code/makefiles 3. The code of a single library resides under a single directory under TOT, e.g. tinylib library is in: TOT/tinylib . The files residing in this directory are: - Top-level Makefile for building the library. - lib.mk defines the library, by including its components' obj.mk files (see 6). - common.mk defines common variables, and is included by all top-level Makefiles. To build a library, call make in this directory, with a build type (default is debug). E.g. - to build a debug version, do: make - to build a release version, do: make BUILD=release 4. A library contains one or more components - all of which reside under a single directory, src. Pure header files also reside here. E.g., always.hpp is included by all source files, as it provides them with common C include files and functionality. E.g. TOT/tinylib/src . 5. Each library component resides in its own directory. E.g. component xyz is under TOT/tinylib/src/xyz . Component's top-level Makefile, obj.mk, source and header files reside there. To build a component object, call make in this directory, with a build type (default is debug). obj.mk defines an object (a component): This is where the object's source files and directory are listed. This information is used while building this object, and to find its header files when building other objects and programs. A component that relies on other components, also includes those components' obj.mk files, so that their header files can be found. 6. Each library component has an accompanying test directory which is under the component's directory. E.g. TOT/tinylib/src/xyz/test . Component test's top-level Makefile, prog.mk, source and header files reside there. To build a component test, call make in this directory, with a build type (default is debug). prog.mk defines a program (an executable): This is where the program's source files and directory are listed. This information is used while building this program. A program that relies on other objects or components, also includes those corresponding obj.mk files, so that their header files can be found. 7. The library's test program resides in its own test directory: E.g. TOT/tinylib/test The test's top-level Makefile, prog.mk, source and header files reside there. To build a library test, call make in this directory, with a build type (default is debug). 8. The top-level Makefile, that builds a component or its test, is called from the source directory. The corresponding built objects or program are placed in a build directory under the source directory. There can be multiple build directories, one for each build type: debug, release or profile. E.g. component xyz's object debug build directory is TOT/tinylib/src/xyz/build/debug . Component xyz's test program release build directory is TOT/tinylib/src/xyz/test/build/release . 9. Users of the library rely on the include directory, E.g. TOT/tinylib/include . This is where the library is defined and distributed to the users. - lib.mk defines the library as a pre-requisite of a program, that relies on that library. - tinylib.hpp is the library's top-level header file. The file includes the header files of its components, with relative path to the include directory. This file is included by source code, that relies on the library, so that the components' header files can be found. A distribution includes: - Copy of the pure header files, e.g. always.hpp . - A build directory with a sub-directory per build type. A copy of the library file should be placed in its corresponding build type directory. - A copy of source code header files, along with their directory structure. The script TOT/tinylib/src/make_dist.cshrc makes a distribution of tinylib into the include directory. Run this script in the src directory. |
The include directory is for users of the library. To isolate users from on-going library development, the header and library files are copied into the include directory.
|