2 Getting started with the Userland Consolidation
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.
14 The Userland consolidation maintains a Git repository at
16 https://github.com/OpenIndiana/oi-userland
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.
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
32 $ git clone https://github.com/OpenIndiana/oi-userland.git /scratch/clone
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:
40 $ cd /scratch/clone/components
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.
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
54 Also, when you start to work with a new archive file - update the source
55 version in an existing recipe component, or start a new one from scratch -
56 you can use 'gmake fetch' to download the archive(s) defined in the new
57 recipe, calculate the checksums and *NOT* remove the archive because its
58 actual checksum does not match the value recorded in the recipe Makefile
59 (if any) so the download is deemed corrupted while you know it is not.
60 There is also a side-effect: by framework recipe, a file in the download
61 location only depends on the component recipe Makefile. So once an archive
62 is "fetched" (downloaded and not removed), it will not be re-verified -
63 the downloading script is just not called. This is a moderate problem,
64 since the "fetch" ability is a helper for recipe-makers doing initial
65 archive downloads in a certain situation, to save some traffic and time
66 on their workstations. You can still remove files fetched by a recipe
67 using 'gmake clobber'.
71 You can build individual components or the contents of the entire gate.
73 Integration with ccache to speed up re-builds
75 If you happen to build the same sources several times (e.g. iterating
76 attempts to produce a working recipe, or maintaining an automated build
77 server), you can benefit from 'ccache' integration in 'oi-userland'.
78 Note that this feature is currently experimental and off by default.
80 The 'ccache' component is available as part of the project repository.
81 Once you have the resulting package installed, you can pass the 'make'
82 argument or environment variable 'ENABLE_CCACHE=true' to wrap the GNU
83 compiler invocations with the caching program - so that the same inputs
84 would re-produce same outputs quickly.
86 You can pre-set this variable in your user account '~/.profile' like this:
88 ### To speed up OI-userland re-builds
92 Note: be wary of ccache's own CCACHE_DISABLE environment variable: any
93 value (empty, "false" etc.) is considered a "true" setting for ccache
94 booleans (and so disables the program, falling through to real compiler).
96 Keeping all sources in one place
98 The Userland consolidation tools automate download of required source
99 tarballs. By default they are kept in each component's directory, but
100 you can centralize it by using the 'USERLAND_ARCHIVES' variable.
102 You can pre-set this variable in your user account '~/.profile' like
103 this (and note that the trailing slash is required):
105 ### For oi-userland source files
106 USERLAND_ARCHIVES="$HOME/Downloads/"
107 export USERLAND_ARCHIVES
111 If you are only working on a single component, you can just build it using
114 setup the workspace for building components
116 $ cd (your-workspace)/components ; gmake setup
118 build the individual component
120 $ cd (component-dir) ; gmake publish
122 Complete Top Down build
124 Complete top down builds are also possible by simply running
126 $ cd (your-workspace)/components
129 The 'publish' target will build each component and publish it to the
132 Tools to help facilitate build zone creation will be integrated
133 shortly. If the zone you create to build your workspace in does not have
134 networking enabled, you can pre-download any community source archives into
135 your workspace from the global with:
137 $ cd (your-workspace)/components
140 You can add parallelism to your builds by adding '-j (jobs)' to your gmake
141 command line arguments. Note that if the host is constrained on resources
142 or the component source Makefiles are poorly thought out, parallel builds
143 can fail - in this case subsequent single-job (sequential) builds should
144 succeed to complete the missing build products.
146 It is worth noting that the OpenIndiana Hipster build server uses the
147 'COMPONENT_BUILD_ARGS=-j4' option by default for moderate parallelization
150 The gate should only incrementally build what it needs to based on what has
151 changed since you last built it.