10139N/AThis is documentation of the Makefile system used in this tree.
10139N/AThis tree builds hundreds of open source modules that are each released
10139N/Aseparately and delivered as source in separate tarballs. These modules
10139N/Aare organized in subdirectories based on the
X.Org module list, though
17835N/Amodules from other sources are included as appropriate. For instance,
18603N/AIn this tree, the term "module" is used for a specific set of source built
17178N/Agenerally from a single tarball from upstream, such as xterm or fontconfig.
10139N/AThe directories grouping these together are referred to as "module type"
11195N/Adirectories - app, lib, font, etc. Each module is thus found in a
10139N/Asubdirectory of the form open-src/<module type>/<module> . Various flags
10139N/Acan be set at either the individual module level or for all modules of a
10139N/AFor each module, at build time the tarball is unpacked to a directory named
18615N/A"unpacked-src", patches applied for post-release bug fixes or customizations,
10139N/Aand then the build is run. Since those subdirectories can be competely
20784N/Arecreated from the source tarball and patches, rebuilding the tree or running
10142N/A"make clobber" simply removes them entirely and recreates them.
12570N/ATo allow building both 32-bit and 64-bit versions in the same build,
17332N/Aand building both sparc and x86 versions in the same tree, the objects are
12773N/Athen built in subdirectories named build-amd64, build-i386, build-sparc,
12773N/Aand build-sparcv9 in each modules' directory. "make clean" or "make clobber"
12773N/Asimply removes these build directories entirely, and lets the next build
10139N/ANote that some modules, especially the fonts, use different build-* patterns
15601N/Afor the variants they build, and thus trying to have both sparc & x86
17332N/Aplatforms building in the same directory at the same time will likely fail
12570N/Aas they stomp on each other in those directories. Running one build then
13551N/AYou should be able to run make commands in any module directory or
17476N/Amodule-type directory, though since most of the intermodule dependencies
15355N/Aare not declared, many modules will break unless you've done a full-tree
17476N/Abuild at some point to populate the proto area with the bits needed.
17005N/A=============================================================================
17026N/AMake targets you can build in each module:
17476N/A------------------------------------------
20152N/AFor most of these you can append _32 or _64 to do just the 32-bit or 64-bit
20261N/Aversions of the targets, while the version listed here repeats for all build
20261N/Atypes set in the BUILD_TYPES variable. These are defined in the
20371N/Amay add additional rules needed for modules of that type.
20784N/A Completely removes build-* directories.
10139N/A Completely removes build-* & unpacked-src directories.
10139N/A Creates unpacked-src directories by unpacking sources from tarball
10139N/A Runs GNU autoconf script or similar configuration steps if
10139N/A needed, including autoreconf or delibtoolize if variables are set.
10139N/A (Runs make source first if needed, and creates build-* directory
10139N/A Compile the software into the binaries that get installed.
10139N/A (Runs make configure first if needed.)
10139N/A Install files into the proto area where make_release_packages
10139N/A will pull them from to make packages and where other parts of
10139N/A the build will use them. (Runs make build first if needed.)
10139N/Amake all (or just "make" with no arguments)
10139N/A equivalent to make build for most modules
10139N/A same as make all, but with compiler optimization flags changed
10139N/A to "-g". (Note that if you haven't done a make clean first,
10139N/A doesn't force a recompile, so running make debug in a directory
10139N/A you already built non-debug may not actually build debug versions.)
10139N/A same as make install, but with compiler optimization flags changed
10139N/A to "-g". (See warning on make debug about doing a make clean first.)
10139N/A module, download it from $(SOURCE_URL). (See "Building from git"
10139N/A section below if MODULE_VERSION=git.)
10139N/A Create a directory new/ containing patches generated against the
10139N/A current tarball. Useful when updating to a new version and patches
10139N/A still apply, but you want to get rid of warnings about patch fuzz
10139N/A See "Building from git" section below.
10139N/A Run the make install rules with DESTDIR set to a temporary directory,
10139N/A that includes all the installed files. If a manifest already exists
20784N/A there, this merges changes with the existing manifest so that you can
20784N/A update when upgrading to a new upstream release.
20784N/A=============================================================================
10139N/AMake targets you can build in parent directories:
10142N/A-------------------------------------------------
10139N/AIn the top-level open-src directory, or any of the module type directories,
20784N/Ayou can run these make commands to run the appropriate targets for all modules
20784N/Ain that directory. The Makefiles at each level all include the same rules
20784N/A Run make all in all subdirectories.
20784N/A Run make clean in all subdirectories.
20784N/A Run make clobber in all subdirectories.
20784N/A Run make clobber in all subdirectories, then make all in all subdirs.
10139N/A Run make install in all subdirectories.
10139N/A Run make download in all subdirectories.
10139N/A Run make source in all subdirectories.
10139N/A Run make git-update in all subdirectories.
10139N/A Run make debug-build in all subdirectories.
10139N/A Run make debug-install in all subdirectories.
10139N/A=============================================================================
12773N/AVariables that can be set in the Makefile for each module:
12773N/A----------------------------------------------------------
10139N/A - Name of the module being built - usually the same as the name of the
10139N/A directory it's being built in and the tarball used for the sources.
11271N/A - Version of the source to use, used by default in the tarball name and
10139N/A source directory unpacked from it. Also exported to the package
10139N/A attributes as __version:$(MODULE_NAME)__ for use in package manifests.
10139N/A "git" - see "Building from git" below
10139N/A "src" - used when there is no upstream tarball, only local sources
10139N/A - Interface Stability to list in attributes section of man page
10139N/A * Required if SUNTOUCHED_MANPAGES is not empty
10139N/A - Name of library built in this module
10139N/A * Required for lib modules if SUNTOUCHED_MANPAGES is not empty
10139N/A or if *.spec files are being used to set library versioning information.
10139N/A - Command to use to uncompress tarball, if not bzcat
10139N/A - Patches to apply to the sources after unpacking the tarball
10139N/A Entries can be either a simple file name or filename,flags
10139N/A to specify flags to be passed to gpatch. The flags argument
10139N/A is most commonly used to specify -p1 to ignore the a/ & b/ path
10139N/A prefixes in git-generated patch files - if no flags are specified,
10139N/A -p0 is passed to treat paths as relative to the top of $(SOURCE_DIR).
10139N/A - Directory containing additional source files to be linked into the
10139N/A source directory by the default_source rule.
10139N/A - If set to "yes", causes the build directory creation to make links for
10139N/A all the files in the source directory into each build directory.
10139N/A - Man pages to add Solaris attributes section and other common Solaris
10139N/A -a '{attribute, value}, ...' - entries for Attributes section table
10139N/A -l libname - add library line to synopsis
10139N/A -p path - add path to command in synopsis
10139N/A - ARC cases that covered this module, both for future reference by engineers
10139N/A - description of the module to be used in license notices or package metadata
10139N/A It should be short, specific, concise text, identifying the technology
10139N/A covered by the associated license(s). It should fit naturally in the
10139N/A sentence "This package may contain XXX." For example, "XXX" might be
10139N/A "the xset command" or "bzip2 compression software." When appropriate,
10139N/A this may begin with "portions of" or another, more specific qualifying
20824N/A - description of software covered by a particular license notice, overrides
20824N/AMODULE_LICENSE_PREPEND, MODULE_LICENSE_APPEND
20784N/A - Files to be added to the beginning or end of LICENSE_FILE when generating
20784N/A the license notice placed in the package.
19082N/A - If an Oracle copyright notice should be added to a package to reflect
19082N/A Oracle's modifications, then this should be the year string to include,
19082N/A usually in the form "first, last", as in "1970, 2038". May be a single
18685N/A year if modifications were all made in the same year.
18580N/A - Third party license tracking number from Oracle's licensing database.
18320N/A - Names of pkgconfig .pc or
.pc.in files in the module, which will be
18320N/A "fixed" to add required -R flags for linking libraries with and remove
18236N/AMODULE_SOURCE_DEPS, MODULE_CONFIGURE_DEPS,
18236N/AMODULE_BUILD_DEPS, MODULE_INSTALL_DEPS
17635N/AMODULE_ADD_SOURCE_TARGETS, MODULE_ADD_CONFIGURE_TARGETS,
17635N/AMODULE_ADD_BUILD_TARGETS, MODULE_ADD_INSTALL_TARGETS
17570N/A in addition to default_* if *_TARGETS is not overridden. Run for each
17332N/A - Additional arguments passed to configure script by default_config rule
17123N/A - Additional environment variables passed to configure script
17005N/A - C Compiler flags passed to configure via CFLAGS variable by
16972N/A - C++ Compiler flags passed to configure via CXXFLAGS variable by
16853N/A - C preprocessor flags (-I & -D) passed to configure via CPPFLAGS
16853N/A variable by default_config rule.
16137N/A - C Compiler flags passed to configure via CFLAGS variable by
16137N/A default_config rule when building debug versions (such as via "make debug")
15601N/A - Linker flags passed to configure via LDFLAGS variable by default_config
15579N/A - If set to "no", don't pass the normal set of -I flags in CPPFLAGS
15448N/A to configure script in default_config rule. MODULE_CPPFLAGS and
15559N/A MODTYPE_CPPFLAGS will still be passed.
15355N/A - If set to "no", don't pass the normal set of linker flags in LDFLAGS
15224N/A to configure script in default_config rule. MODULE_LDFLAGS and
15224N/A MODTYPE_LDFLAGS will still be passed.
14502N/A - If set to "no", don't pass the normal set of default environment variables
14502N/A to configure script in default_config rule. MODULE_CONFIG_ENV and
13992N/A MODTYPE_CONFIG_ENG will still be passed.
13935N/A - If set to "yes", the default_source rule will run autoreconf in the source
13919N/A patches have been applied to the *.ac/*.am/*.in source files.
13795N/A - If set to "yes", the default_config rule will run the script
13662N/A - Additional options passed via LD_OPTIONS environment variable to
13551N/A force options to be used by ld, regardless of options passed by
13326N/A - Additional environment variables passed when calling make
13326N/A by default_build & default_install rules
13276N/A - Additional command line arguments passed when calling make
13276N/A by default_build & default_install
13258N/A - Additional command line arguments passed when calling make
13019N/A - Additional command line arguments passed when calling make
12586N/A to the basenames of files to link from each of those directories to
12467N/A the .so.* names, if both are still delivered.
12393N/AOptional, with non-empty default:
12330N/A* Important, for these, to override the default values, you must not only
12330N/A set the variable, but set another variable <variable>_SET=yes before the
12251N/A attributes section of man page, when generating manifests, and for
12251N/A delivering license and other metadata from the build to the package.
12248N/A Default: $(MODTYPE_PKGHIER)/$(MODULE_NAME), translated to lowercase
12190N/A -
IPS/pkg(5) package classification that the package should be listed
12190N/A under in the Package Manager GUI. Must be one of the values defined
12014N/A - Name of the upstream source of this module, or "NONE"
11416N/A - URL of the web site of the upstream source of this module
11299N/A - Compiler to use, either "suncc" or "gcc".
11271N/A which is set to suncc in the master sources.
11271N/A - make command to use, either "$(MAKE)" or "$(GNUMAKE)".
11271N/A Default: "$(MAKE)" (which is assumed to be Solaris make, not GNU).
11245N/A - Prefix to install files under, passed to configure scripts via --prefix,
11271N/A and used as base for other $(MODULE_*_DIR) paths.
11195N/A - Directory to install documentation under
11271N/A Default: $(MODTYPE_DOC_DIR) if it is set, otherwise
10529N/A - Directory that will be created when the source tarball is unpacked.
10529N/A Default: $(MODULE_NAME)-$(MODULE_VERSION)
10281N/A Set to "NONE" if there is no upstream tarball.
10139N/A - For
X.Org sources, what directory the source tarball & git repo is in
10139N/A - URL to download the SOURCE_TARBALL from when running "make download"
10139N/A Default: $(XORG_RELEASES_URL)/$(SOURCE_TARBALL_DIR)/$(SOURCE_TARBALL_NAME)
10139N/A - URL to check out the current sources via the git code manager if
10139N/A MODULE_VERSION is set to "git" - see "Building from git" below
10139N/A Default: $(XORG_GIT_URL)/$(SOURCE_TARBALL_DIR)/$(MODULE_NAME).git
10139N/A - What type of output to build for this module - usually the word-size of
10139N/A the binaries built (32
and/or 64), but may be set to any string if other
10139N/A distinctions are useful. For most modules that don't build binaries,
10139N/A (fonts, proto headers, docs, etc.) it's set to 32 for simplicity.
10139N/A For each value xx in this list, a build_xx directory will be made and
10139N/A the source_xx, configure_xx, build_xx and install_xx rules run.
10139N/ASOURCE_TARGETS, CONFIGURE_TARGETS, BUILD_TARGETS, INSTALL_TARGETS
10139N/A "make build", and "make install"
10139N/A Defaults: default_source, default_configure, default_build, default_install
10139N/A The *_TARGETS may be appended to by setting the MODTYPE_ADD_*_TARGETS
10139N/A - File created by running the default_configure rule. If this file exists,
10139N/A make will not run the default_configure rule - if it does not exist, it
10139N/A Default: $(SOURCE_DIR)/Makefile
10139N/A - File containing copyright & license information for this module.
10139N/A Will be copied to $(MODULE_PKG_METADATA_DIR) and added as a license
10139N/A File is looked for first in module directory, if not found there,
10139N/A in top-level source directory (SOURCE_DIR).
10139N/A - Name of the license. See the "license" attribute in pkg(5) for details.
10139N/A Must be unique for each license aggregated into a package, so if two
10139N/A upstream modules with different license texts are delivered into the
10139N/A same package, they cannot both have the license name "MIT License", which
10139N/A is why our default string includes the package name to disambiguate.
10139N/A The value "Oracle" is a special case, indicating that Oracle owns all the
10139N/A IP in a module, and can choose to release under the license terms of its
10139N/A choice, while others building from this source tree will be using under
10139N/A the MIT license terms that Oracle has offered the sources under.
10139N/A The license used in this case depends on the LICENSE_CHOICE setting
10139N/A Default: MIT License ($(MODULE_NAME))
10139N/A - For modules in the lib directory, Multi-thread safety level to list in
10139N/A attributes section of SUNTOUCHED_MANPAGES
10139N/A Default: See XInitThreads(3X11)
10139N/A=============================================================================
10139N/A-------------------------------------------------------------------
10139N/ASome settings are common to most, if not all of the modules of a given
10139N/Atype. For those, these variables can be set in
10139N/Aas the MODULE_* versions documented above, and appear in commands before
10139N/Athe MODULE_* versions - the general pattern is
10139N/A foo=<tree-wide-defaults> $(MODTYPE_foo) $(MODULE_foo)
10139N/A - Name of the directory for this module type, usually the same as the
10139N/A - MODTYPE_ADD_CONFIGURE_TARGETS
10139N/AOptional, with non-empty default:
10139N/A[See note in module variable section about setting _SET variables to override]
10139N/A=============================================================================
10139N/Afor the platform being built. You can reference this variable in the
10139N/Anames of other variables to set different values for each platform.
10139N/AFor instance, to build only 64-bit on SPARC, but both 32-bit and 64-bit
10139N/A BUILD_TYPES=$(BUILD_TYPES_$(MACH))
10139N/A=============================================================================
10139N/A---------------------------------
10139N/A"make setup" in the top-level directory of the X gate (
i.e. the parent of
10139N/Adiffer depending on who is building, such as distro branding, licensing,
10139N/ATo force a specific configuration, specify X_BUILD_OPTIONS when running
10139N/A make setup X_BUILD_OPTIONS=opensolaris
10139N/AOtherwise it will strip the last two components of the output of domainname,
10139N/Alowercase them and look for a matching file - for instance, if building on
10139N/AIf X_BUILD_OPTIONS is not found, and a domainname match is not found, then
10139N/A- String used when a reference to the distro name is needed. Mostly used
10139N/A- Vendor name string reported by the X server in the log & protocol.
10139N/A The vendor name needs to include "
X.Org Foundation" for software
10139N/A like cairo that does strstr on VendorName to detect servers built
10139N/A or for xdpyinfo to convert the vendor version integer to a human-friendly
10139N/A in crash messages, for where to get help or check you have the latest
10139N/A- file containing a notice prepended to package license notices for modules
10139N/A containing GPL licensed sources, for builders who wish to specify choice
10139N/A of licenses in modules that are dual-licensed or "GPLv2 or later".
10139N/A pkgmogrify when building packages, for setting distribution-specific
10139N/A- url for a mirror site containing all the upstream tarballs needed during
10139N/A the build - can be any protocol supported by wget. If not set, then
10139N/A "make download" will wget directly from the upstream sites on the internet.
10139N/AOptional, with non-empty default:
10139N/A* Important, for these, to override the default values, you must not only
10139N/A set the variable, but set another variable <variable>_SET=yes before the
10139N/A- For modules with MODULE_LICENSE="Oracle", this controls which license
10139N/A terms are published in the package. This must be set to "Oracle" for
10139N/A builds done for Oracle Solaris. If not set, it defaults to "open",
10139N/A which is the value that all others must use, unless they have obtained
10139N/A special permission from Oracle to license the sources under something
10139N/A other than the standard MIT license terms used for X11 software.
10139N/AXORG_RELEASES_URL & SF_DOWNLOADS_URL
10139N/A- urls for
X.Org & sourceforge mirrors to download tarballs from
10139N/A X.Org, Mesa, pixman, etc. - defaults to anonymous git over http, can
10139N/A change to use another protocol if needed
10139N/A=============================================================================
10139N/A specify on the command line) and tries to isolate out just the
10139N/A build errors for easier reading than the raw build logs.
10139N/A If you did buildit -p, also shows packaging errors.
10139N/Axmake - when you change one file in a large module like xserver and just
10139N/A want to rebuild in that subdirectory of the build-<platform>
10139N/A tree, running xmake will attempt to run make or gmake in that
10139N/A directory with the same flags and environment variables that would
10139N/A be passed from running make in the module make directory
10139N/A xmake can also be used in higher level directories of the tree
10139N/A where it will call dmake with the correct options for parallel
10139N/A=============================================================================
10139N/AFor debugging and development purposes, such as working on the merge of
10139N/Aa
X.org release still in development, you can choose to to check out a
10139N/Athe upstream sources from a the git repository instead of a tarball.
10139N/AYou must *NOT* check in to the master gate a module using this feature,
10139N/Asince this would produce a build that's not reproducible and changing
10139N/ATo use this, set MODULE_VERSION to "git" in a module's Makefile.
10139N/ATo check out a branch other than master, add GIT_BRANCH="branch-name".
10139N/AOnce you've done this "make download" will clone the git repo initially, and
10139N/A"make git-update" will update an existing repo. The clone will be located
10139N/Ain the $(MODULE_NAME)-git subdirectory in the module directory, and the
10139N/A"make source" command will copy it instead of unpacking a tarball.
10139N/A=============================================================================
10139N/AThings we should fix someday, but haven't had time to do yet, include:
10139N/A- Builds are slower than they could be. Things we might be able to do to
10139N/A - Using a cache of configure script results shared among all the
10139N/A - Profiling the builds to see where bottlenecks are
10139N/A- There aren't dependency relationships listed in most of the module
10139N/A and make, because it won't find many of the dependencies - pretty much you
10139N/A have to run ./buildit at the toplevel first to build the entire tree and then
10139N/A go to work on the module you care about. It would be cool if it would do
10139N/A this for you (like I believe the ON tree does), though tracking down all the
10139N/A=============================================================================
10139N/ACopyright (c) 2008, 2016, Oracle
and/or its affiliates. All rights reserved.
10139N/APermission is hereby granted, free of charge, to any person obtaining a
10139N/Acopy of this software and associated documentation files (the "Software"),
10139N/Ato deal in the Software without restriction, including without limitation
10139N/Athe rights to use, copy, modify, merge, publish, distribute, sublicense,
10139N/Aand/or sell copies of the Software, and to permit persons to whom the
10139N/ASoftware is furnished to do so, subject to the following conditions:
10139N/AThe above copyright notice and this permission notice (including the next
10139N/Aparagraph) shall be included in all copies or substantial portions of the
10139N/ATHE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
10139N/AIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
10139N/AFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
10139N/ATHE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
10139N/ALIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
10139N/AFROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER