This is documentation of the Makefile system used in this tree. General Overview: ----------------- This tree builds hundreds of open source modules that are each released separately and delivered as source in separate tarballs. These modules are organized in subdirectories based on the X.Org module list, though modules from other sources are included as appropriate. For instance, the application xterm is built in open-src/app/xterm, while the fontconfig library is in open-src/lib/fontconfig. In this tree, the term "module" is used for a specific set of source built generally from a single tarball from upstream, such as xterm or fontconfig. The directories grouping these together are referred to as "module type" directories - app, lib, font, etc. Each module is thus found in a subdirectory of the form open-src// . Various flags can be set at either the individual module level or for all modules of a module type. For each module, at build time the tarball is unpacked to a directory named "unpacked-src", patches applied for post-release bug fixes or customizations, and then the build is run. Since those subdirectories can be competely recreated from the source tarball and patches, rebuilding the tree or running "make clobber" simply removes them entirely and recreates them. To allow building both 32-bit and 64-bit versions in the same build, and building both sparc and x86 versions in the same tree, the objects are then built in subdirectories named build-amd64, build-i386, build-sparc, and build-sparcv9 in each modules' directory. "make clean" or "make clobber" simply removes these build directories entirely, and lets the next build recreate them as needed. Note that some modules, especially the fonts, use different build-* patterns for the variants they build, and thus trying to have both sparc & x86 platforms building in the same directory at the same time will likely fail as they stomp on each other in those directories. Running one build then the other should work. You should be able to run make commands in any module directory or module-type directory, though since most of the intermodule dependencies are not declared, many modules will break unless you've done a full-tree build at some point to populate the proto area with the bits needed. ============================================================================= Make targets you can build in each module: ------------------------------------------ For most of these you can append _32 or _64 to do just the 32-bit or 64-bit versions of the targets, while the version listed here repeats for all build types set in the BUILD_TYPES variable. These are defined in the open-src/common/Makefile.inc file, though open-src//Makefile.inc may add additional rules needed for modules of that type. make clean Completely removes build-* directories. make clobber Completely removes build-* & unpacked-src directories. make source Creates unpacked-src directories by unpacking sources from tarball and applying patches. make configure Runs GNU autoconf script or similar configuration steps if needed, including autoreconf or delibtoolize if variables are set. (Runs make source first if needed, and creates build-* directory if needed.) make build Compile the software into the binaries that get installed. (Runs make configure first if needed.) make install Install files into the proto area where make_release_packages will pull them from to make packages and where other parts of the build will use them. (Runs make build first if needed.) make all (or just "make" with no arguments) equivalent to make build for most modules make debug same as make all, but with compiler optimization flags changed to "-g". (Note that if you haven't done a make clean first, doesn't force a recompile, so running make debug in a directory you already built non-debug may not actually build debug versions.) make debug-install same as make install, but with compiler optimization flags changed to "-g". (See warning on make debug about doing a make clean first.) make download If open-src/tarballs does not contain the tarball needed for this module, download it from $(SOURCE_URL). (See "Building from git" section below if MODULE_VERSION=git.) make regen-patches Create a directory new/ containing patches generated against the current tarball. Useful when updating to a new version and patches still apply, but you want to get rid of warnings about patch fuzz and line offsets. make git-update See "Building from git" section below. make manifest Run the make install rules with DESTDIR set to a temporary directory, and then generate a pkg manifest in pkg/manifests/$(MODULE_PKGNAME).mf that includes all the installed files. If a manifest already exists there, this merges changes with the existing manifest so that you can update when upgrading to a new upstream release. ============================================================================= Make targets you can build in parent directories: ------------------------------------------------- In the top-level open-src directory, or any of the module type directories, you can run these make commands to run the appropriate targets for all modules in that directory. The Makefiles at each level all include the same rules from open-src/common/Makefile.subdirs to define these. make all Run make all in all subdirectories. make clean Run make clean in all subdirectories. make clobber Run make clobber in all subdirectories. make World Run make clobber in all subdirectories, then make all in all subdirs. make install Run make install in all subdirectories. make download Run make download in all subdirectories. make source Run make source in all subdirectories. make git-update Run make git-update in all subdirectories. make debug-build Run make debug-build in all subdirectories. make debug-install Run make debug-install in all subdirectories. ============================================================================= Variables that can be set in the Makefile for each module: ---------------------------------------------------------- Required for all modules: MODULE_NAME - Name of the module being built - usually the same as the name of the directory it's being built in and the tarball used for the sources. MODULE_VERSION - Version of the source to use, used by default in the tarball name and source directory unpacked from it. Also exported to the package attributes as __version:$(MODULE_NAME)__ for use in package manifests. - Special values: "git" - see "Building from git" below "src" - used when there is no upstream tarball, only local sources Required for some modules: MODULE_STABILITY - Interface Stability to list in attributes section of man page * Required if SUNTOUCHED_MANPAGES is not empty LIBNAME - Name of library built in this module * Required for lib modules if SUNTOUCHED_MANPAGES is not empty or if *.spec files are being used to set library versioning information. Optional, default is empty: SOURCE_UNCOMPRESS - Command to use to uncompress tarball, if not bzcat SOURCE_PATCHES - Patches to apply to the sources after unpacking the tarball Entries can be either a simple file name or filename,flags to specify flags to be passed to gpatch. The flags argument is most commonly used to specify -p1 to ignore the a/ & b/ path prefixes in git-generated patch files - if no flags are specified, -p0 is passed to treat paths as relative to the top of $(SOURCE_DIR). ADDITIONAL_SOURCE_DIR - Directory containing additional source files to be linked into the source directory by the default_source rule. CLONE_SRC - If set to "yes", causes the build directory creation to make links for all the files in the source directory into each build directory. SUNTOUCHED_MANPAGES - Man pages to add Solaris attributes section and other common Solaris man page conventions to, via the open-src/common/suntouch-manpages.pl script. MODULE_SUNTOUCH_MAN_FLAGS - Additional flags to pass to open-src/common/suntouch-manpages.pl, such as -p /usr/bin to add a path of /usr/bin to the command in the synopsis. Available flags are: -a '{attribute, value}, ...' - entries for Attributes section table -l libname - add library line to synopsis -p path - add path to command in synopsis MODULE_ARC_CASES - ARC cases that covered this module, both for future reference by engineers and for publication in opensolaris.arc_url metadata attributes in packages. Must be in the format "ARC/year/case", such as "PSARC/2004/187". MODULE_DESC - description of the module to be used in license notices or package metadata It should be short, specific, concise text, identifying the technology covered by the associated license(s). It should fit naturally in the sentence "This package may contain XXX." For example, "XXX" might be "the xset command" or "bzip2 compression software." When appropriate, this may begin with "portions of" or another, more specific qualifying clause. MODULE_LICENSE_DESC - description of software covered by a particular license notice, overrides MODULE_DESC if set. MODULE_LICENSE_PREPEND, MODULE_LICENSE_APPEND - Files to be added to the beginning or end of LICENSE_FILE when generating the license notice placed in the package. ORACLE_COPYRIGHT_YEARS - If an Oracle copyright notice should be added to a package to reflect Oracle's modifications, then this should be the year string to include, usually in the form "first, last", as in "1970, 2038". May be a single year if modifications were all made in the same year. ORACLE_TPNO - Third party license tracking number from Oracle's licensing database. FIX_PC_FILES - Names of pkgconfig .pc or .pc.in files in the module, which will be "fixed" to add required -R flags for linking libraries with and remove unnecessary Requires.privates lines from. MODULE_SOURCE_DEPS, MODULE_CONFIGURE_DEPS, MODULE_BUILD_DEPS, MODULE_INSTALL_DEPS - Makefile targets/rules that the default_* rules list as dependencies MODULE_ADD_SOURCE_TARGETS, MODULE_ADD_CONFIGURE_TARGETS, MODULE_ADD_BUILD_TARGETS, MODULE_ADD_INSTALL_TARGETS - Additional targets/rules run by "make source", "make configure", etc. in addition to default_* if *_TARGETS is not overridden. Run for each build type. MODULE_CONFIG_OPTS - Additional arguments passed to configure script by default_config rule MODULE_CONFIG_ENV - Additional environment variables passed to configure script by default_config rule MODULE_CFLAGS - C Compiler flags passed to configure via CFLAGS variable by default_config rule. MODULE_CXXFLAGS - C++ Compiler flags passed to configure via CXXFLAGS variable by default_config rule. MODULE_CPPFLAGS - C preprocessor flags (-I & -D) passed to configure via CPPFLAGS variable by default_config rule. MODULE_DEBUG_FLAGS - C Compiler flags passed to configure via CFLAGS variable by default_config rule when building debug versions (such as via "make debug") MODULE_LDFLAGS - Linker flags passed to configure via LDFLAGS variable by default_config rule. USE_DEFAULT_CONFIG_CPPFLAGS - If set to "no", don't pass the normal set of -I flags in CPPFLAGS to configure script in default_config rule. MODULE_CPPFLAGS and MODTYPE_CPPFLAGS will still be passed. USE_DEFAULT_CONFIG_LDFLAGS - If set to "no", don't pass the normal set of linker flags in LDFLAGS to configure script in default_config rule. MODULE_LDFLAGS and MODTYPE_LDFLAGS will still be passed. USE_DEFAULT_CONFIG_ENV - If set to "no", don't pass the normal set of default environment variables to configure script in default_config rule. MODULE_CONFIG_ENV and MODTYPE_CONFIG_ENG will still be passed. AUTORECONF - If set to "yes", the default_source rule will run autoreconf in the source directory, to regenerate autoconf/automake/libtool created files after patches have been applied to the *.ac/*.am/*.in source files. DELIBTOOLIZE - If set to "yes", the default_config rule will run the script open-src/common/delibtoolize.pl to remove libtool calls from Makefiles after running configure. MODULE_LD_OPTIONS - Additional options passed via LD_OPTIONS environment variable to force options to be used by ld, regardless of options passed by libtool/compiler etc. Used by default_build & default_install rules. MODULE_BUILD_ENV - Additional environment variables passed when calling make by default_build & default_install rules MODULE_MAKEFLAGS - Additional command line arguments passed when calling make by default_build & default_install MODULE_BUILD_MAKEFLAGS - Additional command line arguments passed when calling make by default_build MODULE_INSTALL_MAKEFLAGS - Additional command line arguments passed when calling make by default_install MODULE_X11_BINCOMPAT_LINKS MODULE_X11_LIBCOMPAT_LINKS - For binaries previously delivered in /usr/X11/bin or libraries previously delivered in /usr/X11/lib (or their /usr/openwin predecessors), set these to the basenames of files to link from each of those directories to /usr/lib & /usr/bin. For libraries, be sure to include both the .so and the .so.* names, if both are still delivered. Optional, with non-empty default: * Important, for these, to override the default values, you must not only set the variable, but set another variable _SET=yes before the Makefile.inc is included to prevent the default from being set. For example: SOURCE_URL=http://fontconfig.org/release/$(SOURCE_TARBALL_NAME) SOURCE_URL_SET=yes MODULE_PKGNAME - IPS/pkg(5) package name that this module is shipped in. Used in attributes section of man page, when generating manifests, and for delivering license and other metadata from the build to the package. Default: $(MODTYPE_PKGHIER)/$(MODULE_NAME), translated to lowercase MODULE_PKGCLASS - IPS/pkg(5) package classification that the package should be listed under in the Package Manager GUI. Must be one of the values defined by the GUI, which are listed in src/gui/data/opensolaris.org.sections in the pkg gate. Published in package metadata as the info.classification tag for the package. Default: System/X11 UPSTREAM - Name of the upstream source of this module, or "NONE" Published in package metadata as the info.upstream tag for the package. Default: X.Org Foundation UPSTREAM_URL - URL of the web site of the upstream source of this module Published in package metadata as the info.upstream_url tag for the package. Default: http://www.x.org/ MODULE_COMPILER - Compiler to use, either "suncc" or "gcc". Default: $(DEFAULT_COMPILER) setting in common/Makefile.init, which is set to suncc in the master sources. MODULE_MAKE - make command to use, either "$(MAKE)" or "$(GNUMAKE)". Default: "$(MAKE)" (which is assumed to be Solaris make, not GNU). MODULE_PREFIX - Prefix to install files under, passed to configure scripts via --prefix. Default: $(X11_DIR) (aka /usr). MODULE_DOC_DIR - Directory to install documentation under Default: $(MODTYPE_DOC_DIR) if it is set, otherwise $(MODULE_PREFIX)/share/doc/$(MODULE_NAME) SOURCE_DIRNAME - Directory that will be created when the source tarball is unpacked. Default: $(MODULE_NAME)-$(MODULE_VERSION) SOURCE_TARBALL_NAME - Name of tarball file under open-src/tarballs directory for this module. Set to "NONE" if there is no upstream tarball. Default: $(SOURCE_DIRNAME).tar.bz2 SOURCE_TARBALL_DIR - For X.Org sources, what directory the source tarball & git repo is in on freedesktop.org - usually the same as the module type directory in this tree. Default: $(MODTYPE) SOURCE_URL - URL to download the SOURCE_TARBALL from when running "make download" Published in package metadata as the info.source_url tag for the package. Default: $(XORG_RELEASES_URL)/$(SOURCE_TARBALL_DIR)/$(SOURCE_TARBALL_NAME) GIT_URL - URL to check out the current sources via the git code manager if MODULE_VERSION is set to "git" - see "Building from git" below Default: $(XORG_GIT_URL)/$(SOURCE_TARBALL_DIR)/$(MODULE_NAME).git BUILD_TYPES - What type of output to build for this module - usually the word-size of the binaries built (32 and/or 64), but may be set to any string if other distinctions are useful. For most modules that don't build binaries, (fonts, proto headers, docs, etc.) it's set to 32 for simplicity. For each value xx in this list, a build_xx directory will be made and the source_xx, configure_xx, build_xx and install_xx rules run. Default: 32 SOURCE_TARGETS, CONFIGURE_TARGETS, BUILD_TARGETS, INSTALL_TARGETS - Makefile targets/rules to run for "make source", "make configure", "make build", and "make install" Defaults: default_source, default_configure, default_build, default_install The *_TARGETS may be appended to by setting the MODTYPE_ADD_*_TARGETS and/or MODULE_ADD_*_TARGETS variables. AUTOCONF_TARGET - File created by running the default_configure rule. If this file exists, make will not run the default_configure rule - if it does not exist, it will be run. Default: $(SOURCE_DIR)/Makefile LICENSE_FILE - File containing copyright & license information for this module. Will be copied to $(MODULE_PKG_METADATA_DIR) and added as a license action to the package. File is looked for first in module directory, if not found there, in top-level source directory (SOURCE_DIR). Default: COPYING MODULE_LICENSE - Name of the license. See the "license" attribute in pkg(5) for details. Must be unique for each license aggregated into a package, so if two upstream modules with different license texts are delivered into the same package, they cannot both have the license name "MIT License", which is why our default string includes the package name to disambiguate. The value "Oracle" is a special case, indicating that Oracle owns all the IP in a module, and can choose to release under the license terms of its choice, while others building from this source tree will be using under the MIT license terms that Oracle has offered the sources under. The license used in this case depends on the LICENSE_CHOICE setting in open-src/common/Makefile.options. Default: MIT License ($(MODULE_NAME)) MODULE_MTLEVEL - For modules in the lib directory, Multi-thread safety level to list in attributes section of SUNTOUCHED_MANPAGES Default: See XInitThreads(3X11) ============================================================================= Variables that can be set in the Makefile.inc for each module type: ------------------------------------------------------------------- Some settings are common to most, if not all of the modules of a given type. For those, these variables can be set in open-src//Makefile.inc - they have the same meanings and uses as the MODULE_* versions documented above, and appear in commands before the MODULE_* versions - the general pattern is foo= $(MODTYPE_foo) $(MODULE_foo) Required for all module types: MODTYPE - Name of the directory for this module type, usually the same as the directory for the module type in X.Org's source trees. Optional, default is empty: - MODTYPE_SUNTOUCH_MAN_FLAGS - MODTYPE_DESC - MODTYPE_SOURCE_DEPS - MODTYPE_CONFIGURE_DEPS - MODTYPE_BUILD_DEPS - MODTYPE_INSTALL_DEPS - MODTYPE_ADD_SOURCE_TARGETS - MODTYPE_ADD_CONFIGURE_TARGETS - MODTYPE_ADD_BUILD_TARGETS - MODTYPE_ADD_INSTALL_TARGETS - MODTYPE_CONFIG_OPTS - MODTYPE_CONFIG_ENV - MODTYPE_CFLAGS - MODTYPE_CXXFLAGS - MODTYPE_CPPFLAGS - MODTYPE_DEBUG_FLAGS - MODTYPE_LDFLAGS - MODTYPE_LD_OPTIONS - MODTYPE_BUILD_ENV - MODTYPE_MAKEFLAGS - MODTYPE_BUILD_MAKEFLAGS - MODTYPE_INSTALL_MAKEFLAGS Optional, with non-empty default: [See note in module variable section about setting _SET variables to override] - MODTYPE_COMPILER - MODTYPE_DOC_DIR - MODTYPE_MAKE - MODTYPE_PREFIX ============================================================================= Setting per-platform variables: ------------------------------- open-src/common/Makefile.init defines $MACH to be either sparc or i386 for the platform being built. You can reference this variable in the names of other variables to set different values for each platform. For instance, to build only 64-bit on SPARC, but both 32-bit and 64-bit on x86/x64, you can do: BUILD_TYPES_sparc=64 BUILD_TYPES_i386=32 64 BUILD_TYPES=$(BUILD_TYPES_$(MACH)) BUILD_TYPES_SET=yes ============================================================================= Setting builder/distro variables: --------------------------------- "make setup" in the top-level directory of the X gate (i.e. the parent of this open-src disrectory) makes a open-src/common/Makefile.options symlink to one of the Makefile.options.* files to set variables for options that differ depending on who is building, such as distro branding, licensing, and network access. To force a specific configuration, specify X_BUILD_OPTIONS when running "make setup", such as: make setup X_BUILD_OPTIONS=opensolaris Otherwise it will strip the last two components of the output of domainname, lowercase them and look for a matching file - for instance, if building on a machine with a domainname of it.SFBay.Sun.COM, make setup will check for a file named Makefile.options.sun.com. If X_BUILD_OPTIONS is not found, and a domainname match is not found, then Makefile.options.opensolaris as a final fallback. Required settings in Makefile.options.*: DISTRO_NAME - String used when a reference to the distro name is needed. Mostly used in man pages at the moment, such as open-src/xserver/xorg/sun-manpage.patch VENDOR_NAME - Vendor name string reported by the X server in the log & protocol. The vendor name needs to include "X.Org Foundation" for software like cairo that does strstr on VendorName to detect servers built from the X.Org source tree for bug workarounds/compatibility tweaks, or for xdpyinfo to convert the vendor version integer to a human-friendly string. VENDOR_SUPPORT_URL - URL printed by the X server for Xorg -version, in the Xorg.0.log, and in crash messages, for where to get help or check you have the latest version. Optional, with empty default: GPL_CHOICE_FILE - file containing a notice prepended to package license notices for modules containing GPL licensed sources, for builders who wish to specify choice of licenses in modules that are dual-licensed or "GPLv2 or later". PKG_BRANDING_TRANSFORMS - name of a file in pkg/transforms that is added to the list passed to pkgmogrify when building packages, for setting distribution-specific metadata. TARBALL_ARCHIVE - url for a mirror site containing all the upstream tarballs needed during the build - can be any protocol supported by wget. If not set, then "make download" will wget directly from the upstream sites on the internet. Optional, with non-empty default: * Important, for these, to override the default values, you must not only set the variable, but set another variable _SET=yes before the Makefile.inc is included to prevent the default from being set. LICENSE_CHOICE - For modules with MODULE_LICENSE="Oracle", this controls which license terms are published in the package. This must be set to "Oracle" for builds done for Oracle Solaris. If not set, it defaults to "open", which is the value that all others must use, unless they have obtained special permission from Oracle to license the sources under something other than the standard MIT license terms used for X11 software. Default: open XORG_RELEASES_URL & SF_DOWNLOADS_URL - urls for X.Org & sourceforge mirrors to download tarballs from FDO_GIT_URL & XORG_GIT_URL - url for git repositories hosted on freedesktop.org, including X.Org, Mesa, pixman, etc. - defaults to anonymous git over http, can change to use another protocol if needed ============================================================================= Tools for developers to use: Some tools to ease development are available in the util/build-tools directory of the tree. find-build-errors - looks for a log/buildit-XW file (or another file you specify on the command line) and tries to isolate out just the build errors for easier reading than the raw build logs. If you did buildit -p, also shows packaging errors. xmake - when you change one file in a large module like xserver and just want to rebuild in that subdirectory of the build- tree, running xmake will attempt to run make or gmake in that directory with the same flags and environment variables that would be passed from running make in the module make directory xmake can also be used in higher level directories of the tree where it will call dmake with the correct options for parallel builds. ============================================================================= Building from git: For debugging and development purposes, such as working on the merge of a X.org release still in development, you can choose to to check out a the upstream sources from a the git repository instead of a tarball. You must *NOT* check in to the master gate a module using this feature, since this would produce a build that's not reproducible and changing unexpectedly. To use this, set MODULE_VERSION to "git" in a module's Makefile. To check out a branch other than master, add GIT_BRANCH="branch-name". Once you've done this "make download" will clone the git repo initially, and "make git-update" will update an existing repo. The clone will be located in the $(MODULE_NAME)-git subdirectory in the module directory, and the "make source" command will copy it instead of unpacking a tarball. ============================================================================= Known deficiencies (aka TODO): Things we should fix someday, but haven't had time to do yet, include: - Builds are slower than they could be. Things we might be able to do to speed them up include: - Using a cache of configure script results shared among all the components in the tree - Profiling the builds to see where bottlenecks are - There aren't dependency relationships listed in most of the module makefiles - you can't bringover the tree and just cd open-src/xserver/xorg and make, because it won't find many of the dependencies - pretty much you have to run ./buildit at the toplevel first to build the entire tree and then go to work on the module you care about. It would be cool if it would do this for you (like I believe the ON tree does), though tracking down all the dependencies will probably take a while - getting them done for xserver/xorg first would be most useful. ============================================================================= Copyright (c) 2008, 2014, Oracle and/or its affiliates. All rights reserved. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice (including the next paragraph) shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.