/[gentoo]/xml/htdocs/proj/en/gentoo-alt/prefix/bootstrap-macos.xml
Gentoo

Contents of /xml/htdocs/proj/en/gentoo-alt/prefix/bootstrap-macos.xml

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.12 - (show annotations) (download) (as text)
Fri Sep 7 15:38:27 2007 UTC (6 years, 11 months ago) by grobian
Branch: MAIN
Changes since 1.11: +2 -2 lines
File MIME type: application/xml
Fix self links

1 <?xml version="1.0" encoding="UTF-8"?>
2 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/gentoo-alt/prefix/bootstrap-macos.xml,v 1.11 2007/07/22 13:55:58 grobian Exp $ -->
4
5 <guide link="/proj/en/gentoo-alt/prefix/bootstrap-macos.xml" lang="en">
6 <title>Gentoo Prefixed Portage Bootstrap Process for Mac OS X</title>
7
8
9 <author title="Author">
10 <mail link="grobian@gentoo.org">Fabian Groffen</mail>
11 </author>
12
13 <abstract>
14 How to bootstrap Prefixed Portage on your Mac OS X system
15 </abstract>
16
17
18 <!-- The content of this document is licensed under the CC-BY-SA license -->
19 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
20 <license/>
21
22 <version>1.2</version>
23 <date>2007-04-27</date>
24
25 <chapter>
26 <title>Bootstrapping on OS X</title>
27
28 <section><!-- {{{ Introduction -->
29 <title>Introduction</title>
30 <body>
31 <p>
32 Apple Mac OS X was initially supported in the main Gentoo
33 portage tree with the ppc-macos keyword. The approach taken
34 then, however, resulted in too many problems, which was the
35 drive behind creating prefixed portage.
36 </p>
37 <p>
38 Bootstrapping on OS X is relatively simple, as the system
39 itself provides most of the tools get up to speed quickly.
40 Prefixed Portage is tested and supported on Mac OS X Tiger on
41 PPC and x86 architectures. Tests on PPC Panther were
42 successful, but the platform itself isn't fully supported.
43 </p>
44 </body>
45 </section><!-- }}} -->
46
47 <section><!-- {{{ Bootstrapping -->
48 <title>Bootstrapping</title>
49 <body>
50 <p>
51 As prerequisite, you have to have latest Xcode installed.
52 Xcode provides the compiler collection. Bootstrapping is not
53 (yet) supported without it. If you don't have the latest
54 Xcode installed and run into trouble, you can try
55 <c>gcc_select 3.3</c> as root.
56 </p>
57 <p>
58 The first step is to chose a path to install into. We refer
59 to this path as "prefix path", stored in the variable
60 <c>$EPREFIX</c>. Some suggestions for your prefix path are
61 <path>$HOME/Gentoo</path> or <path>$HOME/Library/Gentoo</path>.
62 Whatever you chose, make sure you set it in your environment:
63 </p>
64 <pre caption="Export EPREFIX variable">
65 $ <i>export EPREFIX="$HOME/Gentoo"</i>
66 </pre>
67 <note>
68 tcsh users can use <c>setenv EPREFIX "$HOME/Gentoo"</c>
69 instead.
70 </note>
71 <p>
72 Next, add the following paths in your soon to be prefix to
73 your <c>PATH</c> environment.
74 <path>$EPREFIX/bin</path>,
75 <path>$EPREFIX/usr/bin</path>,
76 <path>$EPREFIX/tmp/bin</path> and
77 <path>$EPREFIX/tmp/usr/bin</path>.
78 Adding these paths makes sure that they will be available
79 later on in the process.
80 </p>
81 <pre caption="Add prefix paths to your PATH">
82 $ <i>export PATH="$EPREFIX/usr/bin:$EPREFIX/bin:$EPREFIX/tmp/usr/bin:$EPREFIX/tmp/bin:$PATH"</i>
83 </pre>
84 <p>
85 Now the path is set, start with downloading the bootstrap
86 script from
87 <uri>http://overlays.gentoo.org/proj/alt/browser/trunk/prefix-overlay/scripts/bootstrap-prefix.sh?format=txt</uri>.
88 From the directory where the bootstrap script was stored execute
89 the following commands:
90 </p>
91 <pre caption="Use the bootstrap script">
92 $ <i>chmod 755 bootstrap-prefix.sh</i>
93 $ <i>./bootstrap-prefix.sh $EPREFIX tree</i>
94 $ <i>./bootstrap-prefix.sh $EPREFIX/tmp wget</i>
95 $ <i>./bootstrap-prefix.sh $EPREFIX/tmp tar</i>
96 $ <i>./bootstrap-prefix.sh $EPREFIX/tmp sed</i>
97 $ <i>./bootstrap-prefix.sh $EPREFIX/tmp python</i>
98 $ <i>./bootstrap-prefix.sh $EPREFIX/tmp gawk</i>
99 $ <i>./bootstrap-prefix.sh $EPREFIX/tmp findutils</i>
100 $ <i>./bootstrap-prefix.sh $EPREFIX portage</i>
101 </pre>
102 <note>Please note that <c>wget</c>, <c>sed</c> and <c>python</c> are
103 installed in <path>$EPREFIX/tmp</path>!</note>
104 <p>
105 The script will setup the <path>$EPREFIX</path>
106 directory, download a portage tree snapshot, unpack it and
107 download and install portage. Afterwards it will try to setup
108 some sane defaults. We continue with a little hack necessary
109 for a successful bootstrap:
110 </p>
111 <pre caption="Setup ld directions">
112 $ <i>export LDFLAGS="-Wl,-search_paths_first -L${EPREFIX}/usr/lib -L${EPREFIX}/lib"</i>
113 $ <i>export CPPFLAGS="-I${EPREFIX}/usr/include"</i>
114 </pre>
115 <note>
116 The <c>-search_paths_first</c> flag is OSX/odcctools only. It
117 instructs the linker to look first in the provided paths, then
118 if that fails in the system (default) paths. This is the
119 default behaviour for many other linkers, including GNU
120 binutils' one as used on Linux.
121 </note>
122 <p>
123 Because we installed some new applications, we will instruct
124 bash to reconsider all paths we have:
125 </p>
126 <pre caption="rehash in bash">
127 $ <i>hash -r</i>
128 </pre>
129 <note>
130 tcsh users can use the <c>rehash</c> command.
131 </note>
132 <p>
133 We continue adding some necessary tools which will deal with
134 many errors and warnings you might see during emerging.
135 </p>
136 <pre caption="emerge sed">
137 $ <i>emerge --oneshot sed</i>
138 </pre>
139 <p>
140 Next, we emerge the <c>bash</c> shell and its dependency
141 ncurses. <c>bash</c> is used extensively within portage and
142 other applications.
143 </p>
144 <pre caption="emerge bash">
145 $ <i>emerge --oneshot bash</i>
146 </pre>
147 <note>
148 It is safe to ignore the "1 config files in XXX need updating"
149 message that appears till the end of the bootstrap process.
150 </note>
151 <p>
152 We continue getting some autotools stuff into our prefix.
153 </p>
154 <pre caption="emerge autotools">
155 $ <i>emerge --oneshot --nodeps "m4"</i>
156 $ <i>emerge --oneshot --nodeps "=autoconf-2.1*" "=autoconf-2.6*" "autoconf-wrapper"</i>
157 $ <i>emerge --oneshot --nodeps "=automake-1.4*" "=automake-1.5*" "=automake-1.6*" "=automake-1.7*" "=automake-1.8*" "automake-wrapper"</i>
158 </pre>
159 <note><c>>=automake-1.9</c> and <c>libtool</c> are not (yet)
160 installed at this stage.</note>
161 <p>
162 Next, we have to get some tools in order to finalise getting
163 the autotools in our prefix. Because we installed <c>wget</c>
164 in a temporary location, let's not forget to install it
165 properly by emerging it now:
166 </p>
167 <pre caption="emerge wget">
168 $ <i>emerge --oneshot --nodeps wget</i>
169 </pre>
170 <p>
171 After this we can emerge texinfo, which <c>automake-1.9</c>
172 needs.
173 </p>
174 <pre caption="emerge texinfo">
175 $ <i>emerge --oneshot --nodeps texinfo</i>
176 </pre>
177 <p>
178 Now we can finish installing the autotools:
179 </p>
180 <pre caption="finalise emerge autotools">
181 $ <i>emerge --oneshot --nodeps "=automake-1.9*" "=automake-1.10*"</i>
182 $ <i>emerge --oneshot --nodeps libtool</i>
183 </pre>
184 <p>
185 Now we have some decent autotooling stuff around, we can get
186 some decent core utilities in our prefix.
187 </p>
188 <pre caption="emerge coreutils">
189 $ <i>emerge --oneshot --nodeps sys-apps/coreutils</i>
190 </pre>
191 <p>
192 Finally we emerge <c>python</c>, <c>findutils</c> and
193 <c>tar</c> in our prefix. These are the last packages that we
194 temporarily installed to bootstrap our system.
195 </p>
196 <pre caption="emerge python">
197 $ <i>emerge --oneshot --nodeps python</i>
198 $ <i>emerge --oneshot --nodeps findutils</i>
199 $ <i>emerge --oneshot --nodeps tar</i>
200 </pre>
201 <p>
202 Before we continue to emerge all ebuilds from <c>system</c>,
203 we first install <c>portage</c>. We need to overwrite the
204 version that was installed by the bootstrap script.
205 Installing a new portage will make sure it uses the tools
206 provided by the prefix, and forget about the temporary
207 installed tools.
208 </p>
209 <pre caption="emerge portage">
210 $ <i>env FEATURES="-collision-protect" emerge --oneshot --nodeps portage</i>
211 </pre>
212 <p>
213 Next, we get GNU <c>awk</c>, as most ebuild expect this
214 <c>awk</c> when they use it.
215 </p>
216 <pre caption="emerge gawk">
217 $ <i>emerge --oneshot gawk</i>
218 </pre>
219 <p>
220 Some, if not many, scripts and tools within a Gentoo system
221 assume the availability of the <c>baselayout</c> package. We
222 make sure here we have it, for this reason. In fact, it would
223 be emerged too late if we wouldn't do it manually now:
224 </p>
225 <pre caption="emerge baselayout-prefix">
226 $ <i>emerge --oneshot --nodeps baselayout-prefix</i>
227 </pre>
228 <p>
229 Now we're about to start the big work, we remove the temporary
230 directory and its use as we got it all in our prefix now.
231 </p>
232 <pre caption="remove tmp directory">
233 $ <i>rm -Rf $EPREFIX/tmp/*</i>
234 $ <i>hash -r</i>
235 </pre>
236 <p>
237 Next, we do the real work where all packages get reemerged in
238 such an order that they make use of packages in the prefix
239 itself.
240 </p>
241 <pre caption="emerge system">
242 $ <i>emerge -e system</i>
243 </pre>
244 <p>
245 This will happily install a lot of stuff and reinstall what
246 you emerged before. This is necessary to avoid compilation
247 failures due to dependencies.
248 </p>
249 <p>
250 Since we have some basic stuff now, we might want the benefit
251 of an updated tree. To use it, emerge <c>subversion</c>:
252 </p>
253 <pre caption="emerge subversion">
254 $ <i>emerge subversion</i>
255 </pre>
256 <p>
257 We can now update the tree. Since snapshots now are actually
258 (anonymous) SVN checkouts of the tree, we can immediately use
259 SVN commands on the tree instead of checking a tree out first.
260 Because Portage knows how to deal with the SVN tree, and the
261 bootstrap script has set a correct <c>SYNC</c> variable in
262 your <path>etc/make.conf</path>, updating the tree is done
263 using:
264 </p>
265 <pre caption="Updating the tree">
266 $ <i>emerge --sync</i>
267 </pre>
268 <note>
269 The prefix portage tree assumes a <e>case-sensitive
270 filesystem</e>. Mac OS X doesn't use this by default. If
271 you experience weird errors while updating or checking out
272 the prefix tree with subversion, check if your filesystem is
273 case-sensitive.
274 </note>
275 <p>
276 To really do this properly, after emerging <c>system</c>, one
277 should re-emerge <c>world</c>, because now all packages can
278 be compiled with all tools from the prefix, instead of based
279 on tools in the system root. Before you do though, this is
280 the good time to set your general <c>USE</c>-flags, such as
281 <c>nls</c> to get localised messages in
282 <path>$EPREFIX/etc/make.conf</path>. In that file, you
283 can also set <c>CFLAGS</c> for your compilation. Be
284 conservative with <c>CFLAGS</c>! Note that the code below is
285 an example, and is meant for inspiration only.
286 </p>
287 <pre caption="Customising the prefix installation - example">
288 $ <i>echo 'USE="unicode nls"' >> $EPREFIX/etc/make.conf</i>
289 $ <i>echo 'CFLAGS="-O2 -pipe"' >> $EPREFIX/etc/make.conf</i>
290 </pre>
291 <note>
292 OSX on Intel users should have <c>-march=prescott</c> in their
293 <c>CFLAGS</c> to avoid compilation errors due to SSE
294 instructions not being enabled.
295 </note>
296 <p>
297 Since we're about to rebuild our system for the last time, we
298 can unset all hacks we made to help the bootstrap process.
299 This time we emerge <c>world</c> to include the packages
300 necessary for <c>subversion</c>.
301 </p>
302 <pre caption="Unsetting LDFLAGS and CPPFLAGS variables">
303 $ <i>unset LDFLAGS</i>
304 $ <i>unset CPPFLAGS</i>
305 $ <i>emerge -e world</i>
306 </pre>
307 <note>
308 tcsh users can use <c>unsetenv LDFLAGS</c> and alike for
309 <c>CPPFLAGS</c>.
310 </note>
311 <p>
312 After <c>world</c> has emerged successfully, your prefix will
313 be set up properly, and you can emerge the whichever tools you
314 choose from the prefix tree.
315 </p>
316 </body>
317 </section><!-- }}} -->
318
319 <section><!-- {{{ Using the Prefix -->
320 <title>Using the Prefix</title>
321 <body>
322 <p>
323 To use your bootstrapped prefix environment, you best start a
324 shell from the prefix, such that your path and other
325 environment variables are set correctly. To facilitate in
326 this, a small helper script can be created by the bootstrap
327 script.
328 </p>
329 <pre caption="Creating a start-script">
330 $ <i>cd $EPREFIX/usr/portage/scripts</i>
331 $ <i>./bootstrap-prefix.sh $EPREFIX startscript</i>
332 </pre>
333 <p>
334 After running this, a script <c>startprefix</c> will be
335 present in <c>$EPREFIX</c>. You can freely move the script to
336 e.g. your homedir for convenience. Running the script will
337 drop you into a prefix shell, where for example <c>emerge</c>
338 is directly at your disposal. Enjoy your prefix!
339 </p>
340 </body>
341 </section>
342
343 </chapter>
344
345 </guide>
346
347 <!-- vim: set expandtab ts=2 sw=2 foldmethod=marker foldenable spell spelllang=en_gb: -->
348 <!-- kate: space-indent on; indent-width 2; replace-tabs on; -->

  ViewVC Help
Powered by ViewVC 1.1.20