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