2N/A# The contents of this file are subject to the terms of the
2N/A# Common Development and Distribution License (the "License").
2N/A# You may not use this file except in compliance with the License.
2N/A# See the License for the specific language governing permissions
2N/A# and limitations under the License.
2N/A# When distributing Covered Code, include this CDDL HEADER in each
2N/A# If applicable, add the following below this CDDL HEADER, with the
2N/A# fields enclosed by brackets "[]" replaced with your own identifying
2N/A# information: Portions Copyright [yyyy] [name of copyright owner]
2N/A# Copyright (c) 2001, 2012, Oracle
and/or its affiliates. All rights reserved.
2N/AWriting Library Makefiles in ON
2N/A===============================
2N/AThis document guides you through the gnarly process of writing library
2N/AMakefiles for the ON consolidation. It assumes that you're comfortable with
2N/Amake(1) and are somewhat familiar with the ON Makefile standards outlined in
2N/AYour library should consist of a hierarchical collection of Makefiles:
2N/A lib/<library>/Makefile:
2N/A This is your library's top-level Makefile. It should contain rules
2N/A for building any ISA-independent targets, such as installing header
2N/A files and building message catalogs, but should defer all other
2N/A targets to ISA-specific Makefiles.
2N/A This is your library's common Makefile. It should contain rules
2N/A and macros which are common to all ISAs. This Makefile should never
2N/A be built explicitly, but instead should be included (using the make
2N/A include mechanism) by all of your ISA-specific Makefiles.
2N/A lib/<library>/<isa>/Makefile
2N/A These are your library's ISA-specific Makefiles, one per ISA
2N/A (usually sparc and i386, and often sparcv9 and amd64). These
2N/A Makefiles should include your common Makefile and then provide any
2N/A needed ISA-specific rules and definitions, perhaps overriding those
2N/A provided in your common Makefile.
2N/ATo simplify their maintenance and construction, $(SRC)/lib has a handful of
2N/Aprovided Makefiles that yours must include; the examples provided throughout
2N/Athe document will show how to use them. Please be sure to consult these
2N/AMakefiles before introducing your own custom build macros or rules.
2N/A This contains the bulk of the macros for building shared objects.
2N/A This contains macros for building 64-bit objects, and should be
2N/A included in Makefiles for 64-bit native ISAs.
2N/A This contains macro overrides for libraries that install into /lib
2N/A This contains rules for building shared objects.
2N/AThe remainder of this document discusses how to write each of your Makefiles
2N/Ain detail, and provides examples from the libinetutil library.
2N/AThe Library Top-level Makefile
2N/A------------------------------
2N/AAs described above, your top-level library Makefile should contain
2N/Arules for building ISA-independent targets, but should defer the
2N/Abuilding of all other targets to ISA-specific Makefiles. The
2N/AISA-independent targets usually consist of:
2N/A Install all library header files into the proto area.
2N/A Can be omitted if your library has no header files.
2N/A Check all library header files for hdrchk compliance.
2N/A Can be omitted if your library has no header files.
2N/A Build and install a message catalog.
2N/A Can be omitted if your library has no message catalog.
2N/AOf course, other targets (such as `cstyle') are fine as well, as long as
2N/Athey are ISA-independent.
2N/Ait easy for you to install and check your library's header files. To use
2N/Athese targets, your Makefile must set the HDRS to the list of your library's
2N/Aheader files to install and HDRDIR to the their location in the source tree.
2N/AIn addition, if your header files need to be installed in a location other
2N/Aappropriate location in the proto area. Once HDRS, HDRDIR and (optionally)
2N/AROOTHDRDIR have been set, your Makefile need only contain
2N/A install_h: $(ROOTHDRS)
2N/Ato bind the provided targets to the standard `install_h' and `check' rules.
2N/Ayou to build and install message catalogs from your library's source files.
2N/ATo install a catalog into the catalog directory in the proto area, define the
2N/APOFILE macro to be the name of your catalog, and specify that the _msg target
2N/Adepends on $(MSGDOMAINPOFILE). The examples below should clarify this.
2N/ATo build a message catalog from arbitrarily many message source files, use
2N/A MSGFILES = $(OBJECTS:%.o=%.i)
2N/A $(POFILE): $(MSGFILES)
2N/A _msg: $(MSGDOMAINPOFILE)
2N/ANote that this example doesn't use grep to find message files, since that can
2N/Amask unreferenced files, and potentially lead to the inclusion of unwanted
2N/Amessages or omission of intended messages in the catalogs. As such, MSGFILES
2N/Ashould be derived from a known list of objects or sources.
2N/AIt is usually preferable to run the source through the C preprocessor prior
2N/Ato extracting messages. To do this, use the ".i" suffix, as shown in the
2N/Aabove example. If you need to skip the C preprocessor, just use the native
2N/Aextracting messages is when you're extracting them from shell scripts; in
2N/ATo build a message catalog from other message catalogs, or from source files
2N/A POFILES = $(SUBDIRS:%=%/_%.po)
2N/A _msg := TARGET = _msg
2N/A $(POFILE): $(POFILES)
2N/A _msg: $(MSGDOMAINPOFILE)
2N/AThe Makefile above would work in conjunction with the following in its
2N/Asubdirectories' Makefiles:
2N/A MSGFILES = $(OBJECTS:%.o=%.i)
2N/A $(POFILE): $(MSGFILES)
2N/ASince this POFILE will be combined with those in other subdirectories by the
2N/Aparent Makefile and that merged file will be installed into the proto area
2N/Avia MSGDOMAINPOFILE, there is no need to use MSGDOMAINPOFILE in this Makefile
2N/A(in fact, using it would lead to duplicate messages in the catalog).
2N/AWhen using any of these targets, keep in mind that other macros, like
2N/AXGETFLAGS and TEXT_DOMAIN may also be set in your Makefile to override or
2N/Aaugment the defaults provided in higher-level Makefiles.
2N/AAs previously mentioned, you should defer all ISA-specific targets to your
2N/AISA-specific Makefiles. You can do this by:
2N/A 1. Setting SUBDIRS to the list of directories to descend into:
2N/A Note that if your library is also built 64-bit, then you should
2N/A $(BUILD64)SUBDIRS += $(MACH64)
2N/A so that SUBDIRS contains $(MACH64) if and only if you're compiling
2N/A 2. Providing a common "descend into SUBDIRS" rule:
2N/A @cd $@; pwd; $(MAKE) $(TARGET)
2N/A 3. Providing a collection of conditional assignments that set TARGET
2N/A clean := TARGET= clean
2N/A clobber := TARGET= clobber
2N/A install := TARGET= install
2N/A lint := TARGET= lint
2N/A stub := TARGET= stub
2N/A stubinstall := TARGET= stub
2N/A The order doesn't matter, but alphabetical is preferable.
2N/A 4. Having the aforementioned targets depend on SUBDIRS:
2N/A all clean clobber install lint stub stubinstall: $(SUBDIRS)
2N/A The `all' target must be listed first so that make uses it as the
2N/A default target; the others might as well be listed alphabetically.
2N/AAs an example of how all of this goes together, here's libinetutil's
2N/Atop-level library Makefile (license notice and copyright omitted):
2N/A $(BUILD64)SUBDIRS += $(MACH64)
2N/A clean := TARGET = clean
2N/A clobber := TARGET = clobber
2N/A install := TARGET = install
2N/A lint := TARGET = lint
2N/A stub := TARGET = stub
2N/A stubinstall := TARGET = stubinstall
2N/A all clean clobber install lint stub stubinstall: $(SUBDIRS)
2N/A install_h: $(ROOTHDRS)
2N/A @cd $@; pwd; $(MAKE) $(TARGET)
2N/AIn concept, your common Makefile should contain all of the rules and
2N/Adefinitions that are the same on all ISAs. However, for reasons of
2N/Amaintainability and cleanliness, you're encouraged to place even
2N/AISA-dependent rules and definitions, as long you express them in an
2N/AISA-independent way (
e.g., by using $(MACH), $(TARGETMACH), and their kin).
2N/A(TARGETMACH is the same as MACH for 32-bit targets, and the same as MACH64
2N/AThe common Makefile can be conceptually split up into four sections:
2N/A 1. A copyright and comments section. Please see the prototype
2N/A copyright message properly. For brevity and clarity, this
2N/A section has been omitted from the examples shown here.
2N/A 2. A list of macros that must be defined prior to the inclusion of
2N/A 3. A list of macros that need not be defined prior to the inclusion
2N/A section is conceptually terminated by the .KEEP_STATE directive.
2N/A 4. A list of targets.
2N/AThe first section is self-explanatory. The second typically consists of the
2N/A Set to the name of the static version of your library, such
2N/A since pattern-matching rules in higher-level Makefiles rely on it,
2N/A even though static libraries are not normally built in ON, and
2N/A are never installed in the proto area. Note that the LIBS macro
2N/A (described below) controls the types of libraries that are built
2N/A when building your library.
2N/A If you are building a loadable module (
i.e., a shared object that
2N/A is only linked at runtime with dlopen(3dl)), specify the name of
2N/A Set to the version of your shared library, such as `.1'. You
2N/A actually do not need to set this prior to the inclusion of
2N/A LIBRARY are so closely related.
2N/A Set to the list of object files contained in your library, such as
2N/A `
a.o b.o'. Usually, this will be the same as your library's source
2N/A files (except with .o extensions), but if your library compiles
2N/A source files outside of the library directory itself, it will
2N/A differ. We'll see an example of this with libinetutil.
2N/AThe third section typically consists of the following macros:
2N/A Set to the list of the types of libraries to build when building
2N/A your library. For dynamic libraries, you should set this to
2N/A `$(DYNLIB) $(LINTLIB)' so that a dynamic library and lint library
2N/A are built. For loadable modules, you should just list DYNLIB,
2N/A since there's no point in building a lint library for libraries
2N/A that are never linked at compile-time.
2N/A If your library needs to be built as a static library (typically
2N/A to be used in other parts of the build), you should set LIBS to
2N/A `$(LIBRARY)'. However, you should do this only when absolutely
2N/A necessary, and you must *never* ship static libraries to customers.
2N/A INSTALL_LIBDIR / INSTALL_LIBDIR64
2N/A (if your library installs to a nonstandard directory)
2N/A INSTALL_LIBDIR and INSTALL_LIBDIR64 are set to the relative
2N/A path of the directories your 32 and 64-bit objects will install
2N/A to, respectively. INSTALL_LIBDIR64 is by default defined as
2N/A $(INSTALL_LIBDIR)/$(MACH64), and so, most libraries need only
2N/A define INSTALL_LIBDIR. For example, FMA objects are generally
2N/A INSTALL_LIBDIR and INSTALL_LIBDIR64 are in turn used by
2N/A the following macros:
2N/A ROOTLIBDIR / ROOTLIBDIR64
2N/A STUBROOTLIBDIR / STUBROOTLIBDIR64
2N/A LROOTLIBDIR / LROOTLIBDIR64
2N/A You should not set these macros directly. However, it is useful
2N/A to understand their purpose.
2N/A ROOTLIBDIR and ROOTLIBDIR64 are set to the directories your
2N/A 32, and 64-bit objects will install to, respectively.
2N/A STUBROOTLIBDIR and STUBROOTLIBDIR64 are set to the directories
2N/A your stub objects are installed to.
2N/A LROOTLIBDIR and LROOTLIBDIR64 are set to the same values as
2N/A ROOTLIBDIR and ROOTLIBDIR64 when the lint target is in force,
2N/A and the values of STUBROOTLIBDIR and STUBROOTLIBDIR64 otherwise.
2N/A They are used when setting the -L flag for linking and lint
2N/A The use of INSTALL_LIBDIR ensures that these 6 macros are always
2N/A defined as a consistent unit. The default value of INSTALL_LIBDIR
2N/A is
usr/lib, meaning that the derived macros have the following
2N/A ROOTLIBDIR $(ROOT)/lib
2N/A ROOTLIBDIR64 $(ROOT)/lib/$(MACH64)
2N/A STUBROOTLIBDIR $(STUBROOT)/lib
2N/A STUBROOTLIBDIR64 $(STUBROOT)/lib/$(MACH64)
2N/A LROOTLIBDIR $(LROOT)/lib
2N/A LROOTLIBDIR64 $(LROOT)/lib/$(MACH64)
2N/A Set to the directory containing your library's source files, such
2N/A as `../common'. Because this Makefile is actually included from
2N/A your ISA-specific Makefiles, make sure you specify the directory
2N/A relative to your library's <isa> directory.
2N/A Set to the list of source files required to build your library.
2N/A you only need to set this when source files from directories other
2N/A than SRCDIR are needed. Keep in mind that SRCS should be set to a
2N/A list of source file *pathnames*, not just a list of filenames.
2N/A LINTLIB-specific SRCS (required if building a lint library)
2N/A Set to a special "lint stubs" file to use when constructing your
2N/A library's lint library. The lint stubs file must be used to
2N/A guarantee that programs that link against your library will be able
2N/A to lint clean. To do this, you must conditionally set SRCS to use
2N/A your stubs file by specifying `LINTLIB := SRCS= $(SRCDIR)/$(LINTSRC)'
2N/A in your Makefile. Of course, you do not need to set this if your
2N/A library does not build a lint library.
2N/A Appended with the list of libraries and library directories needed
2N/A to build your library; minimally "-lc". Note that this should
2N/A *never* be set, since that will inadvertently clear the library
2N/A search path, causing the linker to look in the wrong place for
2N/A Since lint targets also make use of LDLIBS, LDLIBS *must* only
2N/A contain -l and -L directives; all other link-related directives
2N/A should be put in DYNFLAGS (if they apply only to shared object
2N/A construction) or LDFLAGS (if they apply in general).
2N/A Any -L directive that references the workspace proto area
2N/A should use the $(LROOT) macro as follows:
2N/A LROOT resoves to ROOT or STUBROOT depending on whether the
2N/A lint target is in force when LROOT is evaluated. ROOT and STUBROOT
2N/A should not be directly used for -L options in LDLIBS.
2N/A MAPFILES (if necessary)
2N/A Set to the list of mapfiles used to link each ISA-specific version
2N/A of your library. This defaults to `$(SRCDIR)/mapfile-vers' in
2N/A mapfiles or your mapfile doesn't follow the standard naming
2N/A convention. If you have supplemental ISA-dependent mapfiles that
2N/A reside in the respective <isa> directories, you can augment
2N/A MAPFILES += mapfile-vers
2N/A CPPFLAGS (if necessary)
2N/A Appended with any flags that need to be passed to the C
2N/A preprocessor (typically -D and -I flags). Since lint macros use
2N/A CPPFLAGS, CPPFLAGS *must* only contain directives known to the C
2N/A preprocessor. When compiling MT-safe code, CPPFLAGS *must*
2N/A include -D_REENTRANT. When compiling large file aware code,
2N/A CPPFLAGS *must* include -D_FILE_OFFSET_BITS=64.
2N/A Appended with any flags that need to be passed to the C compiler.
2N/A Minimally, append `$(CCVERBOSE)'. Keep in mind that you should
2N/A add any C preprocessor flags to CPPFLAGS, not CFLAGS.
2N/A CFLAGS64 (if necessary)
2N/A Appended with any flags that need to be passed to the C compiler
2N/A when compiling 64-bit code. Since all 64-bit code is compiled
2N/A $(CCVERBOSE), you usually do not need to modify CFLAGS64.
2N/A COPTFLAG (if necessary)
2N/A Set to control the optimization level used by the C compiler when
2N/A compiling 32-bit code. You should only set this if absolutely
2N/A necessary, and it should only contain optimization-related
2N/A COPTFLAG64 (if necessary)
2N/A Set to control the optimization level used by the C compiler when
2N/A compiling 64-bit code. You should only set this if absolutely
2N/A necessary, and it should only contain optimization-related
2N/A LINTFLAGS (if necessary)
2N/A Appended with any flags that need to be passed to lint when
2N/A linting 32-bit code. You should only modify LINTFLAGS in
2N/A rare instances where your code cannot (or should not) be fixed.
2N/A LINTFLAGS64 (if necessary)
2N/A Appended with any flags that need to be passed to lint when
2N/A linting 64-bit code. You should only modify LINTFLAGS64 in
2N/A rare instances where your code cannot (or should not) be fixed.
2N/AOf course, you may use other macros as necessary.
2N/AThe fourth section typically consists of the following targets:
2N/A Build all of the types of the libraries named by LIBS. Must always
2N/A be the first real target in common Makefile. Since the
2N/A higher-level Makefiles already contain rules to build all of the
2N/A different types of libraries, you can usually just specify
2N/A though it should be listed as an empty target if LIBS is set by your
2N/A ISA-specific Makefiles (see above).
2N/A actual library sources. Historically, this target has also been
2N/A used to build the lint library (using LINTLIB), but that usage is
2N/A now discouraged. Thus, this rule should be specified as
2N/AConspicuously absent from this section are the `clean' and `clobber' targets.
2N/Abe provided by your common Makefile. Instead, your common Makefile should
2N/Alist any additional files to remove during a `clean' and `clobber' by
2N/Aappending to the CLEANFILES and CLOBBERFILES macros.
2N/AOnce again, here's libinetutil's common Makefile, which shows how many of
2N/A LIBS = $(DYNLIB) $(LINTLIB)
2N/A $(LINTLIB):= SRCS = $(SRCDIR)/$(LINTSRC)
2N/A LDLIBS += -lsocket -lc
2N/A CFLAGS += $(CCVERBOSE)
2N/A CPPFLAGS += -I$(SRCDIR)
2N/A pics/%.o: $(COMDIR)/%.c
2N/AThe mapfile for libinetutil is named `mapfile-vers' and resides in $(SRCDIR),
2N/Aso the MAPFILES definition is omitted, defaulting to $(SRCDIR)/mapfile-vers.
2N/ANote that for libinetutil, not all of the object files come from SRCDIR. To
2N/Asupport this, an alternate source file directory named COMDIR is defined, and
2N/Athe source files listed in SRCS are specified using both COMDIR and SRCDIR.
2N/AAdditionally, a special build rule is provided to build object files from the
2N/Asources in COMDIR; the rule uses
COMPILE.c and POST_PROCESS_O so that any
2N/Achanges to the compilation and object-post-processing phases will be
2N/Aautomatically picked up.
2N/AThe ISA-Specific Makefiles
2N/A--------------------------
2N/AAs the name implies, your ISA-specific Makefiles should contain macros and
2N/Arules that cannot be expressed in an ISA-independent way. Usually, the only
2N/Arules you will need to put here are `install' and `stubinstall', which have
2N/Adifferent dependencies for 32-bit and 64-bit libraries. For instance, here
2N/Aare the ISA-specific Makefiles for libinetutil. As is often the case, the
2N/A32-bit Makefiles are the same for x86 and sparc, as are the 64-bit Makefiles,
2N/Aso we only show their contents once here:
2N/A install: stubinstall all $(ROOTLIBS) $(ROOTLINKS) $(ROOTLINT)
2N/A stubinstall: stub $(STUBROOTLIBS) $(STUBROOTLINKS)
2N/A install: stubinstall all $(ROOTLIBS64) $(ROOTLINKS64)
2N/A stubinstall: stub $(STUBROOTLIBS64) $(STUBROOTLINKS64)
2N/AObserve that there is no .KEEP_STATE directive in these Makefiles, since all
2N/A.KEEP_STATE directive. Also, note that the 64-bit Makefiles also include
2N/Ahigher level Makefiles included by the common Makefile so that 64-bit
2N/Acompiles work correctly.
2N/ACTF Data in Libraries
2N/A---------------------
2N/ABy default, all position-independent objects are built with CTF data using
2N/Actfconvert, which is then merged together using ctfmerge when the shared
2N/Aobject is built. All C-source objects processed via ctfmerge need to be
2N/Aprocessed via ctfconvert or the build will fail. Objects built from non-C
2N/Asources (such as assembly or C++) are silently ignored for CTF processing.
2N/AFilter libraries that have no source files will need to explicitly disable
2N/AOther issues and questions will undoubtedly arise while you work on your
2N/Alibrary's Makefiles. To help in this regard, a number of libraries of
2N/Avarying complexity have been updated to follow the guidelines and practices
2N/Aoutlined in this document:
2N/A Example of a simple 32-bit only library.
2N/A Example of a simple 32-bit only library that obtains its sources
2N/A from multiple directories.
2N/A Example of a simple loadable module.
2N/A Example of a simple library that builds a message catalog.
2N/A Example of a Makefile hierarchy for a library and a collection
2N/A of related pluggable modules.
2N/A Example of a Makefile hierarchy for a collection of related
2N/A libraries and pluggable modules.
2N/A Also an example of a Makefile hierarchy that supports the
2N/A _dc target for domain and category specific messages.
2N/AOf course, if you still have questions, please do not hesitate to send email
2N/Ato the ON gatekeepers.