README
changeset 38 cd00ea74156e
parent 26 8a9f4e791832
child 151 f9e42a3f7095
equal deleted inserted replaced
37:988ea0021850 38:cd00ea74156e
     1 
     1 
     2 	    Getting started with the Userland Consolidation
     2 	    Getting started with the Userland Consolidation
     3 
     3 
     4 
     4 
     5 Building the bits
     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 [email protected]
       
    11 
       
    12 Overview
     6 
    13 
     7     The Userland consolidation maintains a Mercurial gate at
    14     The Userland consolidation maintains a Mercurial gate at
     8     
    15 
     9         ssh://[email protected]//hg/userland/gate
    16         ssh://[email protected]//hg/userland/gate
    10         
    17 
    11     This gate contains build recipies, patches, IPS manifests, etc. necessary
    18     This gate contains build recipies, patches, IPS manifests, etc. necessary
    12     to download, prep, build, test, package and publish open source software.
    19     to download, prep, build, test, package and publish open source software.
    13     In order to build the contents of the Userland gate, you need to clone it.
    20     The build infrastructure is similiar to that of the SFW consolidation in
    14     Since you are reading this, you probably already have, but in any event
    21     that it makes use of herarchical Makefiles which provide dependency and
    15     you can do so with the following command
    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 Mercurial 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
    16     
    31     
    17     $ hg clone ssh://[email protected]//hg/userland/gate /scratch/clone
    32       $ hg clone ssh://[email protected]//hg/userland/gate /scratch/clone
    18     
       
    19     In order to build the bits either individually or collectively, you must
       
    20     set the WS_TOP environment variable to point to the top of your workspace.
       
    21     
       
    22     $ export WS_TOP=/scratch/clone
       
    23     
       
    24     To build and publish the entire contents of the gate, you can use
       
    25     
       
    26     $ cd /scratch/clone
       
    27     $ gmake publish
       
    28     
       
    29     To build and publish a specific component you need to initialize the
       
    30     workspace by building the tools and creating a repository to publish
       
    31     your results in.  The easiest way to do this is to
       
    32     
       
    33     $ cd /scratch/clone
       
    34     $ gmake setup
       
    35     
       
    36     Once you have initialize the the workspace, you can build individual
       
    37     components by
       
    38     
       
    39     $ cd /scratch/clone/components/(component)
       
    40     $ gmake publish
       
    41     
       
    42     All of the bits are are built will be published to the repository created
       
    43     by the setup step (file:///scratch/clone/repo/)  If you build the entire
       
    44     contents of the gate, individual build logs for each component will be
       
    45     located at /scratch/clone/logs/(target):(component).log
       
    46 
    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:
    47 
    39 
       
    40       $ export WS_TOP=/scratch/clone
       
    41       $ cd /scratch/clone/components
       
    42       $ gmake download
       
    43 
       
    44     This will use GNU make and the downloading tool in the gate to walk through
       
    45     all of the component directories downloading and validating the community
       
    46     source archives from the gate machine or their canonical source repository.
       
    47 
       
    48     There are two variation to this that you may find interesting.  First, you
       
    49     can cause gmake(1) to perform it's work in parallel by adding '-j (jobs)'
       
    50     to the command line.  Second, if you are only interested in working on a
       
    51     particular component, you can change directories to that component's
       
    52     directory and use 'gmake download' from that to only get it's source
       
    53     archive.
       
    54 
       
    55 Building the Bits.
       
    56 
       
    57     You can build individual components or the contents of the entire gate.
       
    58     Regardless of how you build the gate, you must set WS_TOP in the calling
       
    59     environment to point to the top of your workspace. Ex:
       
    60 
       
    61       $ export WS_TOP=/scratch/clone
       
    62 
       
    63   Component build
       
    64 
       
    65     If you are only working on a single component, you can just build it using
       
    66     following:
       
    67 
       
    68       setup the workspace for building components
       
    69 
       
    70         $ cd ${WS_TOP}/components ; gmake setup
       
    71 
       
    72       build the individual component
       
    73 
       
    74         $ cd (component-dir) ; gmake publish
       
    75 
       
    76   Complete Top Down build  
       
    77 
       
    78     Complete top down builds are also possible by simply running
       
    79 
       
    80       $ cd ${WS_TOP}/components
       
    81       $ gmake package-install
       
    82 
       
    83     The 'package-install' target will build each component, publish it to the
       
    84     workspace IPS repo and install it in the running environment.  As a result,
       
    85     it is strongly recommended that you only perform complete top down builds
       
    86     in a zone.  Tools to help facilitate build zone creation will be integrated
       
    87     shortly.  If the zone you create to build your workspace in does not have
       
    88     networking enabled, you can pre-download any community source archives into
       
    89     your workspace from the global with:
       
    90 
       
    91       $ cd ${WS_TOP}/components
       
    92       $ gmake download
       
    93 
       
    94   You can add parallelism to your builds by adding '-j (jobs)' to your gmake
       
    95   command line arguments.
       
    96 
       
    97   The gate should only incrementally build what it needs to based on what has
       
    98   changed since you last built it.