README
author Norm Jacobs <Norm.Jacobs@Sun.COM>
Mon, 27 Dec 2010 14:11:48 -0800
changeset 55 959a7cdab6c8
parent 38 cd00ea74156e
child 151 f9e42a3f7095
permissions -rw-r--r--
Added tag build-156 for changeset c29995a38868
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
2
125cd5d2cd9e include gmake example
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
     1
26
8a9f4e791832 packaging changes including canonical manifest support with manifest validation
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 2
diff changeset
     2
	    Getting started with the Userland Consolidation
2
125cd5d2cd9e include gmake example
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
     3
125cd5d2cd9e include gmake example
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
     4
38
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
     5
Getting Started
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
     6
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
     7
    This README provides a very brief overview of the gate, how to retrieve
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
     8
    a copy, and how to build it.  Detailed documentation about the Userland
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
     9
    gate can be found in the 'doc' directory.  Questions or comments about
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    10
    the gate can be addressed to [email protected]
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    11
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    12
Overview
2
125cd5d2cd9e include gmake example
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents:
diff changeset
    13
26
8a9f4e791832 packaging changes including canonical manifest support with manifest validation
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 2
diff changeset
    14
    The Userland consolidation maintains a Mercurial gate at
38
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    15
26
8a9f4e791832 packaging changes including canonical manifest support with manifest validation
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 2
diff changeset
    16
        ssh://[email protected]//hg/userland/gate
38
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    17
26
8a9f4e791832 packaging changes including canonical manifest support with manifest validation
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 2
diff changeset
    18
    This gate contains build recipies, patches, IPS manifests, etc. necessary
8a9f4e791832 packaging changes including canonical manifest support with manifest validation
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 2
diff changeset
    19
    to download, prep, build, test, package and publish open source software.
38
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    20
    The build infrastructure is similiar to that of the SFW consolidation in
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    21
    that it makes use of herarchical Makefiles which provide dependency and
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    22
    recipe information for building the components.  In order to build the
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    23
    contents of the Userland gate, you need to clone it.  Since you are
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    24
    reading this, you probably already have.
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    25
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    26
Getting the Bits
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    27
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    28
    As mentioned, the gate is stored in a Mercurial repository.  In order to
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    29
    build or develop in the gate, you will need to clone it.  You can do so
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    30
    with the following command
26
8a9f4e791832 packaging changes including canonical manifest support with manifest validation
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 2
diff changeset
    31
    
38
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    32
      $ hg clone ssh://[email protected]//hg/userland/gate /scratch/clone
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    33
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    34
    This will create a replica of the various pieces that are checked into the
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    35
    source code management system, but it does not retrieve the community
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    36
    source archives associated with the gate content.  To download the
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    37
    community source associated with your cloned workspace, you will need to
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    38
    execute the following:
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    39
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    40
      $ export WS_TOP=/scratch/clone
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    41
      $ cd /scratch/clone/components
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    42
      $ gmake download
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    43
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    44
    This will use GNU make and the downloading tool in the gate to walk through
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    45
    all of the component directories downloading and validating the community
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    46
    source archives from the gate machine or their canonical source repository.
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    47
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    48
    There are two variation to this that you may find interesting.  First, you
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    49
    can cause gmake(1) to perform it's work in parallel by adding '-j (jobs)'
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    50
    to the command line.  Second, if you are only interested in working on a
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    51
    particular component, you can change directories to that component's
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    52
    directory and use 'gmake download' from that to only get it's source
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    53
    archive.
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    54
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    55
Building the Bits.
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    56
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    57
    You can build individual components or the contents of the entire gate.
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    58
    Regardless of how you build the gate, you must set WS_TOP in the calling
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    59
    environment to point to the top of your workspace. Ex:
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    60
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    61
      $ export WS_TOP=/scratch/clone
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    62
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    63
  Component build
26
8a9f4e791832 packaging changes including canonical manifest support with manifest validation
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 2
diff changeset
    64
38
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    65
    If you are only working on a single component, you can just build it using
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    66
    following:
26
8a9f4e791832 packaging changes including canonical manifest support with manifest validation
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 2
diff changeset
    67
38
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    68
      setup the workspace for building components
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    69
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    70
        $ cd ${WS_TOP}/components ; gmake setup
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    71
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    72
      build the individual component
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    73
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    74
        $ cd (component-dir) ; gmake publish
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    75
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    76
  Complete Top Down build  
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    77
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    78
    Complete top down builds are also possible by simply running
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    79
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    80
      $ cd ${WS_TOP}/components
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    81
      $ gmake package-install
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    82
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    83
    The 'package-install' target will build each component, publish it to the
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    84
    workspace IPS repo and install it in the running environment.  As a result,
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    85
    it is strongly recommended that you only perform complete top down builds
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    86
    in a zone.  Tools to help facilitate build zone creation will be integrated
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    87
    shortly.  If the zone you create to build your workspace in does not have
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    88
    networking enabled, you can pre-download any community source archives into
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    89
    your workspace from the global with:
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    90
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    91
      $ cd ${WS_TOP}/components
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    92
      $ gmake download
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    93
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    94
  You can add parallelism to your builds by adding '-j (jobs)' to your gmake
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    95
  command line arguments.
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    96
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    97
  The gate should only incrementally build what it needs to based on what has
cd00ea74156e package audits should pass pkglint
Norm Jacobs <Norm.Jacobs@Sun.COM>
parents: 26
diff changeset
    98
  changed since you last built it.