493N/AThis is documentation of the Makefile system used in this tree.
493N/AThis tree builds dozens of open source modules that are each released
493N/Aseparately and delivered as source in seperate 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"
493N/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
493N/AFor each module, at build time the tarball is unpacked, patches applied for
493N/Apost-release bug fixes or customizations, and then the build is run.
493N/ATo allow building both 32-bit and 64-bit versions in the same build,
493N/Athis all happens in subdirectories named build_32 & build_64 in each
493N/Amodules' directory. Since those subdirectories are competely recreatable
493N/Afrom the source tarball and patches, rebuilding the tree or running make clean
493N/Asimply removes them entirely and recreates them.
493N/AYou should be able to run make commands in any module directory or
493N/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
493N/Atypes set in the BUILD_TYPES variable. These are defined in the
493N/Amay add additional rules needed for modules of that type.
493N/A Completely removes build_* directories.
493N/A Creates build_* 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.
493N/A (Runs make source first if needed.)
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
493N/A same as make all, but with compiler optimization flags changed
493N/A to "-g". (Note that if you haven't done a make clean first,
493N/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.)
493N/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
493N/A See "Building from git" section below.
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.
493N/A Run make clean 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
493N/A source directory unpacked from it.
493N/A "git" - see "Building from git" below
493N/A "src" - used when there is no upstream tarball, only local sources
493N/A "NONE" - used when no build_* directories are created
493N/ARequired for some modules:
493N/A - Package name that this module is shipped in, to list in attributes section
493N/A * Required if SUNTOUCHED_MANPAGES is not empty
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,
493N/A -p0 is passed to treat paths as relative to the top of $(BUILD_DIR).
493N/A - Directory containing additional source files to be linked into the
493N/A build directory by the default_source rule.
493N/A - Man pages to add Solaris attributes section and other common Solaris
493N/AMODULE_SUNTOUCH_MAN_FLAGS
493N/A synopsis. Available flags are:
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
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
493N/AMODULE_SOURCE_DEPS, MODULE_CONFIGURE_DEPS,
493N/AMODULE_BUILD_DEPS, MODULE_INSTALL_DEPS
493N/A - Additional arguments passed to configure script by default_config rule
493N/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
493N/A - C preprocessor flags (-I & -D) passed to configure via CPPFLAGS
493N/A variable by default_config rule.
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.
493N/A - If set to "yes", the default_config rule will run autoreconf before
493N/A files after 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
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
493N/A - Compiler to use, either "suncc" or "gcc".
493N/A which is set to suncc in the master sources.
493N/A - make command to use, either "$(MAKE)" or "$(GNUMAKE)".
493N/A Default: "$(MAKE)" (which is assumed to be Solaris make, not GNU).
493N/A - Prefix to install files under, passed to configure scripts via --prefix.
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)
493N/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
493N/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
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.
493N/A Will be copied to $(PROTODIR)/licenses/<path>/COPYING
493N/A path is the same as the directory & subdirectory the module source is in.
493N/A File is looked for first in module directory, if not found there,
493N/A in top-level source directory (SOURCE_DIR).
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
493N/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:
493N/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
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.
493N/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=============================================================================
493N/A- urls for
X.Org & sourceforge mirrors to download tarballs from
493N/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
493N/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
493N/A want to rebuild in that subdirectory of the build_32 or build_64
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
493N/A=============================================================================
493N/AFor debugging and development purposes, such as working on the merge of
493N/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:
493N/A- Builds are slow. Painfully slow. Things we might be able to do to
493N/A - Using a cache of configure script results shared among all the
493N/A machines can build more than one bit at a time.
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=============================================================================
493N/ACopyright 2008 Sun Microsystems, Inc. All rights reserved.
493N/AUse subject to license terms.
493N/APermission is hereby granted, free of charge, to any person obtaining a
493N/Acopy of this software and associated documentation files (the
493N/A"Software"), to deal in the Software without restriction, including
493N/Awithout limitation the rights to use, copy, modify, merge, publish,
493N/Adistribute,
and/or sell copies of the Software, and to permit persons
493N/Ato whom the Software is furnished to do so, provided that the above
493N/Acopyright notice(s) and this permission notice appear in all copies of
493N/Athe Software and that both the above copyright notice(s) and this
493N/Apermission notice appear in supporting documentation.
493N/ATHE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
493N/AOR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
493N/AMERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
493N/AOF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
493N/AHOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
493N/AINDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
493N/AFROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
493N/ANEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
493N/AWITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
493N/AExcept as contained in this notice, the name of a copyright holder
493N/Ashall not be used in advertising or otherwise to promote the sale, use
493N/Aor other dealings in this Software without prior written authorization
493N/Aof the copyright holder.