|
Getting started with the Userland Consolidation
|
|
|
Getting Started
|
|
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 oi-dev@openindiana.org.
|
|
Overview
|
|
The Userland consolidation maintains a Git repository at
|
|
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.
|
The build infrastructure is similiar to that of the SFW consolidation in
|
that it makes use of herarchical Makefiles which provide dependency and
|
recipe information for building the components. In order to build the
|
contents of the Userland gate, you need to clone it. Since you are
|
reading this, you probably already have.
|
|
Getting the Bits
|
|
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
|
|
$ 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
|
source archives associated with the gate content. To download the
|
community source associated with your cloned workspace, you will need to
|
execute the following:
|
|
$ cd /scratch/clone/components
|
$ gmake download
|
|
This will use GNU make and the downloading tool in the gate to walk through
|
all of the component directories downloading and validating the community
|
source archives from the gate machine or their canonical source repository.
|
|
There are two variation to this that you may find interesting. First, you
|
can cause gmake(1) to perform it's work in parallel by adding '-j (jobs)'
|
to the command line. Second, if you are only interested in working on a
|
particular component, you can change directories to that component's
|
directory and use 'gmake download' from that to only get it's source
|
archive.
|
|
Building the Bits
|
|
You can build individual components or the contents of the entire gate.
|
|
Keeping all sources in one place
|
|
The Userland consolidation tools automate download of required source
|
tarballs. By default they are kept in each component's directory, but
|
you can centralize it by using the `USERLAND_ARCHIVES` variable.
|
|
You can pre-set this variable in your user account `~/.profile` like
|
this (and note that the trailing slash is required):
|
|
````
|
# For oi-userland
|
USERLAND_ARCHIVES="$HOME/Downloads/"
|
export USERLAND_ARCHIVES
|
````
|
|
Component build
|
|
If you are only working on a single component, you can just build it using
|
following:
|
|
setup the workspace for building components
|
|
$ cd (your-workspace)/components ; gmake setup
|
|
build the individual component
|
|
$ cd (component-dir) ; gmake publish
|
|
If you build several components, and some are required dependencies for the
|
subsequent ones, and you publish them to your local repository to get the
|
job done faster, you may need to set `ENCUMBERED=yes` so that the packaging
|
tools agree to build packages with dependencies outside the official repo.
|
|
You can pre-set this variable in your user account `~/.profile` like this:
|
|
````
|
# To build oi-userland with deps on external repos, like the local one
|
ENCUMBERED=yes
|
export ENCUMBERED
|
````
|
|
Complete Top Down build
|
|
Complete top down builds are also possible by simply running
|
|
$ cd (your-workspace)/components
|
$ gmake publish
|
|
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
|
your workspace from the global with:
|
|
$ cd (your-workspace)/components
|
$ gmake download
|
|
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.
|
|
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.
|
