README

   1
   2             Getting started with the Userland Consolidation
   3
   4
   5 Getting Started
   6
   7     This README provides a very brief overview of the gate, how to retrieve
   8     a copy, and how to build it.  Detailed documentation about the Userland
   9     gate can be found in the 'doc' directory.  Questions or comments about
  10     the gate can be addressed to oi-dev@openindiana.org.
  11
  12 Overview
  13
  14     The Userland consolidation maintains a Git repository at
  15
  16         https://github.com/OpenIndiana/oi-userland
  17
  18     This gate contains build recipies, patches, IPS manifests, etc. necessary
  19     to download, prep, build, test, package and publish open source software.
  20     The build infrastructure is similiar to that of the SFW consolidation in
  21     that it makes use of herarchical Makefiles which provide dependency and
  22     recipe information for building the components.  In order to build the
  23     contents of the Userland gate, you need to clone it.  Since you are
  24     reading this, you probably already have.
  25
  26 Getting the Bits
  27
  28     As mentioned, the gate is stored in a Git repository.  In order to
  29     build or develop in the gate, you will need to clone it.  You can do so
  30     with the following command
  31
  32       $ git clone https://github.com/OpenIndiana/oi-userland.git /scratch/clone
  33
  34     This will create a replica of the various pieces that are checked into the
  35     source code management system, but it does not retrieve the community
  36     source archives associated with the gate content.  To download the
  37     community source associated with your cloned workspace, you will need to
  38     execute the following:
  39
  40       $ cd /scratch/clone/components
  41       $ gmake download
  42
  43     This will use GNU make and the downloading tool in the gate to walk through
  44     all of the component directories downloading and validating the community
  45     source archives from the gate machine or their canonical source repository.
  46
  47     There are two variation to this that you may find interesting.  First, you
  48     can cause gmake(1) to perform it's work in parallel by adding '-j (jobs)'
  49     to the command line.  Second, if you are only interested in working on a
  50     particular component, you can change directories to that component's
  51     directory and use 'gmake download' from that to only get it's source
  52     archive.
  53
  54 Building the Bits.
  55
  56     You can build individual components or the contents of the entire gate.
  57
  58   Component build
  59
  60     If you are only working on a single component, you can just build it using
  61     following:
  62
  63       setup the workspace for building components
  64
  65         $ cd (your-workspace)/components ; gmake setup
  66
  67       build the individual component
  68
  69         $ cd (component-dir) ; gmake publish
  70
  71   Complete Top Down build
  72
  73     Complete top down builds are also possible by simply running
  74
  75       $ cd (your-workspace)/components
  76       $ gmake publish
  77
  78     The 'publish' target will build each component and publish it to the
  79     workspace IPS repo.
  80     Tools to help facilitate build zone creation will be integrated
  81     shortly.  If the zone you create to build your workspace in does not have
  82     networking enabled, you can pre-download any community source archives into
  83     your workspace from the global with:
  84
  85       $ cd (your-workspace)/components
  86       $ gmake download
  87
  88   You can add parallelism to your builds by adding '-j (jobs)' to your gmake
  89   command line arguments.
  90
  91   The gate should only incrementally build what it needs to based on what has
  92   changed since you last built it.