~olbohlen/oi-userland.git

			@@ -7,13 +7,13 @@
			This README provides a very brief overview of the gate, how to retrieve
			a copy, and how to build it. Detailed documentation about the Userland
			gate can be found in the 'doc' directory. Questions or comments about
			the gate can be addressed to userland-discuss@opensolaris.org.
			the gate can be addressed to oi-dev@openindiana.org.

			Overview

			The Userland consolidation maintains a Mercurial gate at
			The Userland consolidation maintains a Git repository at

			ssh://anon@hg.opensolaris.org//hg/userland/gate
			https://github.com/OpenIndiana/oi-userland

			This gate contains build recipies, patches, IPS manifests, etc. necessary
			to download, prep, build, test, package and publish open source software.
			@@ -25,11 +25,11 @@

			Getting the Bits

			As mentioned, the gate is stored in a Mercurial repository. In order to
			As mentioned, the gate is stored in a Git repository. In order to
			build or develop in the gate, you will need to clone it. You can do so
			with the following command

			$ hg clone ssh://anon@hg.opensolaris.org//hg/userland/gate /scratch/clone

			$ git clone https://github.com/OpenIndiana/oi-userland.git /scratch/clone

			This will create a replica of the various pieces that are checked into the
			source code management system, but it does not retrieve the community
			@@ -51,9 +51,68 @@
			directory and use 'gmake download' from that to only get it's source
			archive.

			Building the Bits.
			Also, when you start to work with a new archive file - update the source
			version in an existing recipe component, or start a new one from scratch -
			you can use 'gmake fetch' to download the archive(s) defined in the new
			recipe, calculate the checksums and NOT remove the archive because its
			actual checksum does not match the value recorded in the recipe Makefile
			(if any) so the download is deemed corrupted while you know it is not.
			There is also a side-effect: by framework recipe, a file in the download
			location only depends on the component recipe Makefile. So once an archive
			is "fetched" (downloaded and not removed), it will not be re-verified -
			the downloading script is just not called. This is a moderate problem,
			since the "fetch" ability is a helper for recipe-makers doing initial
			archive downloads in a certain situation, to save some traffic and time
			on their workstations. You can still remove files fetched by a recipe
			using 'gmake clobber'.

			Building the Bits

			You can build individual components or the contents of the entire gate.

			Integration with ccache to speed up re-builds

			If you happen to build the same sources several times (e.g. iterating
			attempts to produce a working recipe, or maintaining an automated build
			server), you can benefit from 'ccache' integration in 'oi-userland'.
			Note that this feature is currently experimental and off by default.

			The 'ccache' component is available as part of the project repository.
			Once you have the resulting package installed, you can pass the 'make'
			argument or environment variable 'ENABLE_CCACHE=true' to wrap the GNU
			compiler invocations with the caching program - so that the same inputs
			would re-produce same outputs quickly.

			You can pre-set this variable in your user account '~/.profile' like this:

			### To speed up OI-userland re-builds
			ENABLE_CCACHE=true
			export ENABLE_CCACHE

			Note: be wary of ccache's own CCACHE_DISABLE environment variable: any
			value (empty, "false" etc.) is considered a "true" setting for ccache
			booleans (and so disables the program, falling through to real compiler).

			Keeping all sources in one place

			The Userland consolidation tools automate download of required source
			tarballs. By older default they were kept in each component's directory,
			but you could centralize it by using the 'USERLAND_ARCHIVES' variable.
			Recently the defaults change to pre-initialize 'USERLAND_ARCHIVES' to
			point into '$(WS_TOP)/archives/' unless customized by the caller - for
			example, to share the common download area between multiple workspaces.

			You can pre-set this variable in your user account '~/.profile' like
			this (and note that the trailing slash is required):

			### For oi-userland source files
			USERLAND_ARCHIVES="$HOME/Downloads/"
			export USERLAND_ARCHIVES

			See also the 'make-rules/shared-macros.mk' for 'INTERNAL_ARCHIVE_MIRROR',
			'EXTERNAL_ARCHIVE_MIRROR' and envvar 'DOWNLOAD_SEARCH_PATH' to get some
			ideas about using HTTP mirrors to e.g. reduce network load and lags if you
			can access a country- or organization-local mirror of opensource projects.

			Component build

			@@ -68,7 +127,7 @@

			$ cd (component-dir) ; gmake publish

			Complete Top Down build
			Complete Top Down build

			Complete top down builds are also possible by simply running

			@@ -77,6 +136,7 @@

			The 'publish' target will build each component and publish it to the
			workspace IPS repo.

			Tools to help facilitate build zone creation will be integrated
			shortly. If the zone you create to build your workspace in does not have
			networking enabled, you can pre-download any community source archives into
			@@ -85,8 +145,15 @@
			$ cd (your-workspace)/components
			$ gmake download

			You can add parallelism to your builds by adding '-j (jobs)' to your gmake
			command line arguments.
			You can add parallelism to your builds by adding '-j (jobs)' to your gmake
			command line arguments. Note that if the host is constrained on resources
			or the component source Makefiles are poorly thought out, parallel builds
			can fail - in this case subsequent single-job (sequential) builds should
			succeed to complete the missing build products.

			The gate should only incrementally build what it needs to based on what has
			changed since you last built it.
			It is worth noting that the OpenIndiana Hipster build server uses the
			'COMPONENT_BUILD_ARGS=-j4' option by default for moderate parallelization
			of its builds.

			The gate should only incrementally build what it needs to based on what has
			changed since you last built it.