README.md
author Rich Burridge <rich.burridge@oracle.com>
Mon, 17 Apr 2017 11:12:35 -0700
changeset 7875 fdce0f6fd2bd
parent 7785 51080767e1a9
permissions -rw-r--r--
25904287 Adjust lftp to build with the GNU compilers
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
7763
2a3817cf33cb 25727021 s/java.net/github.com/g (tweak README format)
John Beck <John.Beck@Oracle.COM>
parents: 7760
diff changeset
     1
# Getting started with the Userland Consolidation
2a3817cf33cb 25727021 s/java.net/github.com/g (tweak README format)
John Beck <John.Beck@Oracle.COM>
parents: 7760
diff changeset
     2
2a3817cf33cb 25727021 s/java.net/github.com/g (tweak README format)
John Beck <John.Beck@Oracle.COM>
parents: 7760
diff changeset
     3
## Getting Started
7785
51080767e1a9 25752641 ditch README in favor of README.md, clean it up a bit
John Beck <John.Beck@Oracle.COM>
parents: 7769
diff changeset
     4
This README provides a very brief overview of the gate (i.e., source
51080767e1a9 25752641 ditch README in favor of README.md, clean it up a bit
John Beck <John.Beck@Oracle.COM>
parents: 7769
diff changeset
     5
code repository), how to retrieve a copy, and how to build it.  Detailed
51080767e1a9 25752641 ditch README in favor of README.md, clean it up a bit
John Beck <John.Beck@Oracle.COM>
parents: 7769
diff changeset
     6
documentation about the Userland gate can be found in the `doc` directory.
7763
2a3817cf33cb 25727021 s/java.net/github.com/g (tweak README format)
John Beck <John.Beck@Oracle.COM>
parents: 7760
diff changeset
     7
2a3817cf33cb 25727021 s/java.net/github.com/g (tweak README format)
John Beck <John.Beck@Oracle.COM>
parents: 7760
diff changeset
     8
## Overview
2a3817cf33cb 25727021 s/java.net/github.com/g (tweak README format)
John Beck <John.Beck@Oracle.COM>
parents: 7760
diff changeset
     9
The Userland consolidation maintains a project at
7760
4ab84455407c 25727021 s/java.net/github.com/g
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    10
4ab84455407c 25727021 s/java.net/github.com/g
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    11
     https://github.com/oracle/solaris-userland
4ab84455407c 25727021 s/java.net/github.com/g
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    12
7785
51080767e1a9 25752641 ditch README in favor of README.md, clean it up a bit
John Beck <John.Beck@Oracle.COM>
parents: 7769
diff changeset
    13
That repo contains build recipes, patches, IPS (i.e., pkg(7)) manifests,
51080767e1a9 25752641 ditch README in favor of README.md, clean it up a bit
John Beck <John.Beck@Oracle.COM>
parents: 7769
diff changeset
    14
and other files necessary to download, prep, build, test, package and publish
51080767e1a9 25752641 ditch README in favor of README.md, clean it up a bit
John Beck <John.Beck@Oracle.COM>
parents: 7769
diff changeset
    15
open source software.  The build infrastructure makes use of hierarchical
51080767e1a9 25752641 ditch README in favor of README.md, clean it up a bit
John Beck <John.Beck@Oracle.COM>
parents: 7769
diff changeset
    16
Makefiles which provide dependency and recipe information for building
51080767e1a9 25752641 ditch README in favor of README.md, clean it up a bit
John Beck <John.Beck@Oracle.COM>
parents: 7769
diff changeset
    17
the components.  In order to build the contents of the Userland gate,
51080767e1a9 25752641 ditch README in favor of README.md, clean it up a bit
John Beck <John.Beck@Oracle.COM>
parents: 7769
diff changeset
    18
you need to clone it.  Since you are reading this, you may already have.
7763
2a3817cf33cb 25727021 s/java.net/github.com/g (tweak README format)
John Beck <John.Beck@Oracle.COM>
parents: 7760
diff changeset
    19
2a3817cf33cb 25727021 s/java.net/github.com/g (tweak README format)
John Beck <John.Beck@Oracle.COM>
parents: 7760
diff changeset
    20
## Getting the Bits
7785
51080767e1a9 25752641 ditch README in favor of README.md, clean it up a bit
John Beck <John.Beck@Oracle.COM>
parents: 7769
diff changeset
    21
The canonical repository internal to Oracle is stored in Mercurial, and
51080767e1a9 25752641 ditch README in favor of README.md, clean it up a bit
John Beck <John.Beck@Oracle.COM>
parents: 7769
diff changeset
    22
is mirrored to an external Git repository on GitHub.  In order to build
51080767e1a9 25752641 ditch README in favor of README.md, clean it up a bit
John Beck <John.Beck@Oracle.COM>
parents: 7769
diff changeset
    23
or develop in the gate, you will need to clone it.  You can do so with one
51080767e1a9 25752641 ditch README in favor of README.md, clean it up a bit
John Beck <John.Beck@Oracle.COM>
parents: 7769
diff changeset
    24
of the following commands.  Internal:
7760
4ab84455407c 25727021 s/java.net/github.com/g
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    25
7785
51080767e1a9 25752641 ditch README in favor of README.md, clean it up a bit
John Beck <John.Beck@Oracle.COM>
parents: 7769
diff changeset
    26
    $ hg clone ssh://[email protected]//gates/gate /scratch/clone
51080767e1a9 25752641 ditch README in favor of README.md, clean it up a bit
John Beck <John.Beck@Oracle.COM>
parents: 7769
diff changeset
    27
51080767e1a9 25752641 ditch README in favor of README.md, clean it up a bit
John Beck <John.Beck@Oracle.COM>
parents: 7769
diff changeset
    28
External:
51080767e1a9 25752641 ditch README in favor of README.md, clean it up a bit
John Beck <John.Beck@Oracle.COM>
parents: 7769
diff changeset
    29
51080767e1a9 25752641 ditch README in favor of README.md, clean it up a bit
John Beck <John.Beck@Oracle.COM>
parents: 7769
diff changeset
    30
    $ git clone https://github.com/oracle/solaris-userland /scratch/clone
7760
4ab84455407c 25727021 s/java.net/github.com/g
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    31
4ab84455407c 25727021 s/java.net/github.com/g
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    32
This will create a replica of the various pieces that are checked into the
4ab84455407c 25727021 s/java.net/github.com/g
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    33
source code management system, but it does not retrieve the community
4ab84455407c 25727021 s/java.net/github.com/g
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    34
source archives associated with the gate content.  To download the
4ab84455407c 25727021 s/java.net/github.com/g
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    35
community source associated with your cloned workspace, you will need to
4ab84455407c 25727021 s/java.net/github.com/g
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    36
execute the following:
4ab84455407c 25727021 s/java.net/github.com/g
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    37
7769
96a1241fc627 25727021 s/java.net/github.com/g (README tweaks requested by OGHO)
John Beck <John.Beck@Oracle.COM>
parents: 7763
diff changeset
    38
    $ cd /scratch/clone/components
96a1241fc627 25727021 s/java.net/github.com/g (README tweaks requested by OGHO)
John Beck <John.Beck@Oracle.COM>
parents: 7763
diff changeset
    39
    $ gmake download
7760
4ab84455407c 25727021 s/java.net/github.com/g
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    40
4ab84455407c 25727021 s/java.net/github.com/g
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    41
This will use GNU make and the downloading tool in the gate to walk through
4ab84455407c 25727021 s/java.net/github.com/g
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    42
all of the component directories downloading and validating the community
4ab84455407c 25727021 s/java.net/github.com/g
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    43
source archives from the gate machine or their canonical source repository.
4ab84455407c 25727021 s/java.net/github.com/g
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    44
4ab84455407c 25727021 s/java.net/github.com/g
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    45
There are two variation to this that you may find interesting.  First, you
7785
51080767e1a9 25752641 ditch README in favor of README.md, clean it up a bit
John Beck <John.Beck@Oracle.COM>
parents: 7769
diff changeset
    46
can cause gmake(1) to perform its work in parallel by adding `-j (jobs)`
7760
4ab84455407c 25727021 s/java.net/github.com/g
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    47
to the command line.  Second, if you are only interested in working on a
4ab84455407c 25727021 s/java.net/github.com/g
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    48
particular component, you can change directories to that component's
7785
51080767e1a9 25752641 ditch README in favor of README.md, clean it up a bit
John Beck <John.Beck@Oracle.COM>
parents: 7769
diff changeset
    49
directory and use `gmake download` from that to only get its source
7760
4ab84455407c 25727021 s/java.net/github.com/g
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    50
archive.
7763
2a3817cf33cb 25727021 s/java.net/github.com/g (tweak README format)
John Beck <John.Beck@Oracle.COM>
parents: 7760
diff changeset
    51
2a3817cf33cb 25727021 s/java.net/github.com/g (tweak README format)
John Beck <John.Beck@Oracle.COM>
parents: 7760
diff changeset
    52
## Building the Bits.
2a3817cf33cb 25727021 s/java.net/github.com/g (tweak README format)
John Beck <John.Beck@Oracle.COM>
parents: 7760
diff changeset
    53
You can build individual components or the contents of the entire gate.
2a3817cf33cb 25727021 s/java.net/github.com/g (tweak README format)
John Beck <John.Beck@Oracle.COM>
parents: 7760
diff changeset
    54
2a3817cf33cb 25727021 s/java.net/github.com/g (tweak README format)
John Beck <John.Beck@Oracle.COM>
parents: 7760
diff changeset
    55
### Component build
2a3817cf33cb 25727021 s/java.net/github.com/g (tweak README format)
John Beck <John.Beck@Oracle.COM>
parents: 7760
diff changeset
    56
If you are only working on a single component, you can just build it using
7760
4ab84455407c 25727021 s/java.net/github.com/g
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    57
following:
4ab84455407c 25727021 s/java.net/github.com/g
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    58
7769
96a1241fc627 25727021 s/java.net/github.com/g (README tweaks requested by OGHO)
John Beck <John.Beck@Oracle.COM>
parents: 7763
diff changeset
    59
Setup the workspace for building components
7760
4ab84455407c 25727021 s/java.net/github.com/g
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    60
4ab84455407c 25727021 s/java.net/github.com/g
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    61
    $ cd (your-workspace)/components ; gmake setup
4ab84455407c 25727021 s/java.net/github.com/g
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    62
7769
96a1241fc627 25727021 s/java.net/github.com/g (README tweaks requested by OGHO)
John Beck <John.Beck@Oracle.COM>
parents: 7763
diff changeset
    63
Build the individual component
7760
4ab84455407c 25727021 s/java.net/github.com/g
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    64
4ab84455407c 25727021 s/java.net/github.com/g
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    65
    $ cd (component-dir) ; gmake publish
7763
2a3817cf33cb 25727021 s/java.net/github.com/g (tweak README format)
John Beck <John.Beck@Oracle.COM>
parents: 7760
diff changeset
    66
2a3817cf33cb 25727021 s/java.net/github.com/g (tweak README format)
John Beck <John.Beck@Oracle.COM>
parents: 7760
diff changeset
    67
### Complete Top Down build
2a3817cf33cb 25727021 s/java.net/github.com/g (tweak README format)
John Beck <John.Beck@Oracle.COM>
parents: 7760
diff changeset
    68
Complete top down builds are also possible by simply running
7760
4ab84455407c 25727021 s/java.net/github.com/g
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    69
7769
96a1241fc627 25727021 s/java.net/github.com/g (README tweaks requested by OGHO)
John Beck <John.Beck@Oracle.COM>
parents: 7763
diff changeset
    70
    $ cd (your-workspace)/components
96a1241fc627 25727021 s/java.net/github.com/g (README tweaks requested by OGHO)
John Beck <John.Beck@Oracle.COM>
parents: 7763
diff changeset
    71
    $ gmake publish
7760
4ab84455407c 25727021 s/java.net/github.com/g
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    72
7785
51080767e1a9 25752641 ditch README in favor of README.md, clean it up a bit
John Beck <John.Beck@Oracle.COM>
parents: 7769
diff changeset
    73
The `publish` target will build each component and publish it to the
7760
4ab84455407c 25727021 s/java.net/github.com/g
John Beck <John.Beck@Oracle.COM>
parents:
diff changeset
    74
workspace IPS repo.
7769
96a1241fc627 25727021 s/java.net/github.com/g (README tweaks requested by OGHO)
John Beck <John.Beck@Oracle.COM>
parents: 7763
diff changeset
    75
7785
51080767e1a9 25752641 ditch README in favor of README.md, clean it up a bit
John Beck <John.Beck@Oracle.COM>
parents: 7769
diff changeset
    76
- You can add parallelism to your builds by adding `-j (jobs)` to your gmake
7763
2a3817cf33cb 25727021 s/java.net/github.com/g (tweak README format)
John Beck <John.Beck@Oracle.COM>
parents: 7760
diff changeset
    77
  command line arguments.
2a3817cf33cb 25727021 s/java.net/github.com/g (tweak README format)
John Beck <John.Beck@Oracle.COM>
parents: 7760
diff changeset
    78
- The gate should only incrementally build what it needs to based on what has
2a3817cf33cb 25727021 s/java.net/github.com/g (tweak README format)
John Beck <John.Beck@Oracle.COM>
parents: 7760
diff changeset
    79
  changed since you last built it.
7769
96a1241fc627 25727021 s/java.net/github.com/g (README tweaks requested by OGHO)
John Beck <John.Beck@Oracle.COM>
parents: 7763
diff changeset
    80
  
96a1241fc627 25727021 s/java.net/github.com/g (README tweaks requested by OGHO)
John Beck <John.Beck@Oracle.COM>
parents: 7763
diff changeset
    81
# Copyright
96a1241fc627 25727021 s/java.net/github.com/g (README tweaks requested by OGHO)
John Beck <John.Beck@Oracle.COM>
parents: 7763
diff changeset
    82
Copyright (c) 2010, 2017, Oracle and/or its affiliates. All rights reserved.