README.Makefiles revision f808c858fa61e7769218966759510a8b1190dfcf
b7ff1e47da4653d2ff1ec7b489e6067fed29d8c5Lennart Poettering# CDDL HEADER START
c904f64d84db8c4eebedf210ba10893f19ba05edLennart Poettering# The contents of this file are subject to the terms of the
7d640cdf66a7c032c871ccfe0ee4ad56f7e3869bLennart Poettering# Common Development and Distribution License (the "License").
62170515a17d0771aa38c8e7711a7a60c8d14d2fLennart Poettering# You may not use this file except in compliance with the License.
f80781eaf9f927d7b4d5e66116e3f3a4242e6fa1Lennart Poettering# You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
f80781eaf9f927d7b4d5e66116e3f3a4242e6fa1Lennart Poettering# or http://www.opensolaris.org/os/licensing.
4466194c43a25bc51b21226f04245131e698bb3fLennart Poettering# See the License for the specific language governing permissions
f80781eaf9f927d7b4d5e66116e3f3a4242e6fa1Lennart Poettering# and limitations under the License.
222ae6a8d7e27dd36552cb9574e63cbdfdf2d264Lennart Poettering# When distributing Covered Code, include this CDDL HEADER in each
c904f64d84db8c4eebedf210ba10893f19ba05edLennart Poettering# file and include the License file at usr/src/OPENSOLARIS.LICENSE.
c904f64d84db8c4eebedf210ba10893f19ba05edLennart Poettering# If applicable, add the following below this CDDL HEADER, with the
099663ff8c117303af369a4d412dafed0c5614c2Lennart Poettering# fields enclosed by brackets "[]" replaced with your own identifying
cebe0d41e4d5b3fdd9d521116cc029bcb819c90dLennart Poettering# information: Portions Copyright [yyyy] [name of copyright owner]
099663ff8c117303af369a4d412dafed0c5614c2Lennart Poettering# CDDL HEADER END
0e456f978134100d2e0cc28c7205b3abefcc9cdeLennart Poettering# Copyright 2006 Sun Microsystems, Inc. All rights reserved.
0e456f978134100d2e0cc28c7205b3abefcc9cdeLennart Poettering# Use is subject to license terms.
b9a2a36b519ccd79c4198e7dda4e657d597a14adLennart Poettering# ident "%Z%%M% %I% %E% SMI"
222ae6a8d7e27dd36552cb9574e63cbdfdf2d264Lennart PoetteringWriting Library Makefiles in ON
7d76f312889d54dcfe6fdde6eb055e890e7a615bLennart Poettering===============================
67370238b55df4126e505007d46deaff8bb55a36Lennart PoetteringThis document guides you through the gnarly process of writing library
abf96c874cd644cf6c66da95d376aa330382376eLennart PoetteringMakefiles for the ON consolidation. It assumes that you're comfortable with
abf96c874cd644cf6c66da95d376aa330382376eLennart Poetteringmake(1) and are somewhat familiar with the ON Makefile standards outlined in
68c7d001f4117f0c3d0a4582e32cbb03ae5fac57Lennart PoetteringMakefile Overview
68c7d001f4117f0c3d0a4582e32cbb03ae5fac57Lennart Poettering-----------------
3d57c6ab801f4437f12948e29589e3d00c3ad9dbLennart PoetteringYour library should consist of a hierarchical collection of Makefiles:
9d8677dad260d7dc20146f8affe3d376daff7c19Lennart Poettering lib/<library>/Makefile:
9d8677dad260d7dc20146f8affe3d376daff7c19Lennart Poettering This is your library's top-level Makefile. It should contain rules
9d8677dad260d7dc20146f8affe3d376daff7c19Lennart Poettering for building any ISA-independent targets, such as installing header
222ae6a8d7e27dd36552cb9574e63cbdfdf2d264Lennart Poettering files and building message catalogs, but should defer all other
d7cc2987a50e62af6b806f1f56f526cf219a0d97Lennart Poettering targets to ISA-specific Makefiles.
16b879e3eeb25f7b0d517682a4e8b62f39c149f2Kay Sievers This is your library's common Makefile. It should contain rules
16b879e3eeb25f7b0d517682a4e8b62f39c149f2Kay Sievers and macros which are common to all ISAs. This Makefile should never
b9a2a36b519ccd79c4198e7dda4e657d597a14adLennart Poettering be built explicitly, but instead should be included (using the make
b9a2a36b519ccd79c4198e7dda4e657d597a14adLennart Poettering include mechanism) by all of your ISA-specific Makefiles.
9408a2d295a312a5472345090e28e0502570494bLennart Poettering lib/<library>/<isa>/Makefile
68c7d001f4117f0c3d0a4582e32cbb03ae5fac57Lennart Poettering These are your library's ISA-specific Makefiles, one per ISA
ba1a55152c50dfbcd3d4a64353b95f4a2f37985eLennart Poettering (usually sparc and i386, and often sparcv9 and amd64). These
9408a2d295a312a5472345090e28e0502570494bLennart Poettering Makefiles should include your common Makefile and then provide any
d7cc2987a50e62af6b806f1f56f526cf219a0d97Lennart Poettering needed ISA-specific rules and definitions, perhaps overriding those
d7cc2987a50e62af6b806f1f56f526cf219a0d97Lennart Poettering provided in your common Makefile.
3f7a8c4e9f1d3ce48919e24eb2c9d56dd6fd88d8Kay SieversTo simplify their maintenance and construction, $(SRC)/lib has a handful of
3f7a8c4e9f1d3ce48919e24eb2c9d56dd6fd88d8Kay Sieversprovided Makefiles that yours must include; the examples provided throughout
b9a2a36b519ccd79c4198e7dda4e657d597a14adLennart Poetteringthe document will show how to use them. Please be sure to consult these
b9a2a36b519ccd79c4198e7dda4e657d597a14adLennart PoetteringMakefiles before introducing your own custom build macros or rules.
b9a2a36b519ccd79c4198e7dda4e657d597a14adLennart Poettering This contains the bulk of the macros for building shared objects.
b9a2a36b519ccd79c4198e7dda4e657d597a14adLennart Poettering This contains macros for building 64-bit objects, and should be
3f7a8c4e9f1d3ce48919e24eb2c9d56dd6fd88d8Kay Sievers included in Makefiles for 64-bit native ISAs.
260abb780a135e4cae8c10715c7e85675efc345aLennart Poettering This contains macro overrides for libraries that install into /lib
260abb780a135e4cae8c10715c7e85675efc345aLennart Poettering This contains rules for building shared objects.
7d9e57d2cf671f7173324942e0eb9de0d030c505Kay SieversThe remainder of this document discusses how to write each of your Makefiles
3f7a8c4e9f1d3ce48919e24eb2c9d56dd6fd88d8Kay Sieversin detail, and provides examples from the libinetutil library.
7d9e57d2cf671f7173324942e0eb9de0d030c505Kay SieversThe Library Top-level Makefile
7d9e57d2cf671f7173324942e0eb9de0d030c505Kay Sievers------------------------------
7d9e57d2cf671f7173324942e0eb9de0d030c505Kay SieversAs described above, your top-level library Makefile should contain
7d9e57d2cf671f7173324942e0eb9de0d030c505Kay Sieversrules for building ISA-independent targets, but should defer the
7d9e57d2cf671f7173324942e0eb9de0d030c505Kay Sieversbuilding of all other targets to ISA-specific Makefiles. The
7d9e57d2cf671f7173324942e0eb9de0d030c505Kay SieversISA-independent targets usually consist of:
a49408ec64063023524b964064d393c1fce36e4aKay Sievers Install all library header files into the proto area.
a49408ec64063023524b964064d393c1fce36e4aKay Sievers Can be omitted if your library has no header files.
a8f11321c209830a35edd0357e8def5d4437d854Lennart Poettering Check all library header files for hdrchk compliance.
81253930180bac6b6fb372a9c7bea724bd795c86Lennart Poettering Can be omitted if your library has no header files.
81253930180bac6b6fb372a9c7bea724bd795c86Lennart Poettering Build and install a message catalog.
7fc7012b8b54bdd6610d32649d4ee9c938a4843dLennart Poettering Can be omitted if your library has no message catalog.
1a6f4df6c9437ed631080b7e006f666326063d36Lennart PoetteringOf course, other targets (such as `cstyle') are fine as well, as long as
1a6f4df6c9437ed631080b7e006f666326063d36Lennart Poetteringthey are ISA-independent.
a49408ec64063023524b964064d393c1fce36e4aKay SieversThe ROOTHDRS and CHECKHDRS targets are provided in lib/Makefile.lib to make
3db48a7850d9ceb8e81ec4ad410520c05c008763Lennart Poetteringit easy for you to install and check your library's header files. To use
3db48a7850d9ceb8e81ec4ad410520c05c008763Lennart Poetteringthese targets, your Makefile must set the HDRS to the list of your library's
3db48a7850d9ceb8e81ec4ad410520c05c008763Lennart Poetteringheader files to install and HDRDIR to the their location in the source tree.
2e0d98fa87a4e399763c8235abe56be4f8ac7fb8Lennart PoetteringIn addition, if your header files need to be installed in a location other
2e0d98fa87a4e399763c8235abe56be4f8ac7fb8Lennart Poetteringthan $(ROOT)/usr/include, your Makefile must also set ROOTHDRDIR to the
62170515a17d0771aa38c8e7711a7a60c8d14d2fLennart Poetteringappropriate location in the proto area. Once HDRS, HDRDIR and (optionally)
a49408ec64063023524b964064d393c1fce36e4aKay SieversROOTHDRDIR have been set, your Makefile need only contain
b5c6cf87342bedeb67fbbc4f3f512af1603a461cLennart Poettering install_h: $(ROOTHDRS)
3185a36b05d53757a412f847d8c510978b9b00f0Lennart Poettering check: $(CHECKHDRS)
3185a36b05d53757a412f847d8c510978b9b00f0Lennart Poetteringto bind the provided targets to the standard `install_h' and `check' rules.
b8bb3e8f346468e61dcc7a6aba5e7ac9c623d964Lennart PoetteringSimilar rules are provided (in $(SRC)/Makefile.msg.targ) to make it easy for
f959c5e63a9080cbff42ac4160154f8a6b508e7aLennart Poetteringyou to build and install message catalogs from your library's source files.
7f6d613516020bf390d8de25bbbb2551ea8dade0Lennart PoetteringTo install a catalog into the catalog directory in the proto area, define the
c32e0c40f7e706e3ebcd101187d5ced96f083491Lennart PoetteringPOFILE macro to be the name of your catalog, and specify that the _msg target
c32e0c40f7e706e3ebcd101187d5ced96f083491Lennart Poetteringdepends on $(MSGDOMAINPOFILE). The examples below should clarify this.