Attachment #13178 for bug #22711

View | Details | Raw Unified | Return to bug 22711
Collapse All | Expand All




<?xml-stylesheet href="/xsl/guide.xsl" type="text/xsl"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">

<guide link="/doc/en/stage-building-guide.xml">

<author title = "Author"><mail link = "zhen@gentoo.org">John P. Davis</mail></author>
<author title = "Author"><mail link = "avenj@gentoo.org">Jon Portnoy</mail></author>

<version>1.1</version>
<date>12 Jun 2003</date>

<abstract>This guide is an explanation on how to build stages for
Gentoo Linux.</abstract>

<chapter>
	<title>Preliminaries</title>
	<section>
		<title>Introduction</title>
		<body>
		<p>This guide is an explanation on how to build fresh
		stages for Gentoo Linux using stager, our stage-building application.</p>
		things: </p>

		<ul>
		<li>You are a Gentoo Linux Developer.</li>
		<li>You have access to the <i>gentoo-src</i> module of CVS.</li>
		</ul>

	</body>
	</section>

		<p>Before building anything, it is necessary to get the required source, tools, etc.
		First of all, make sure that you have the <i>gentoo-src</i> module checked out of CVS
		and that it is up to date. The build scripts change frequently, so make sure that you stay current.
		If you do not have access to the gentoo-src module, a snapshot of stager can be found at
		<uri>http://cvs.gentoo.org/~avenj/stager/</uri>.
		Additionally, the most recent experimental stage1 tarball is 
		required. This can usually be found at <path>experimental/x86/stages</path> on any Gentoo mirror. The tarball that you will be looking for is 
		<i>stage1-x86-1.4_pre<i>DATE</i></i>.tar.bz2, where <i>DATE</i> is the most recent date available. 
		</p>
		
		</body>

	<section>
		<title>First Steps</title>
		<body>
		<p>First, create a directory on a nice big partition to hold all of the build files. Next, copy the <path>stager</path>
		in <path>/usr/src/grp</path>, but of course, yours can be different. Next, copy the <path>stager</path>
		directory from <i>gentoo-src</i> into this new
		directory (which will be referred to as <path>/usr/src/build</path> in this document). Alternatively, extract the tarball of the snapshot into this directory. 
		Finially, create a directory inside <path>/usr/src/build</path> called <i>stages</i>
		and put the experimental stage1 tarball in there.
		</p>

		<pre caption="Getting Ready">
# <c>mkdir /usr/src/build </c>
<codenote>You can change the above path to whatever you want.</codenote>

# <c>cp -R /gentoo-src/stager/ /usr/src/build</c>
# <c>cd /usr/src/build/stager ; mkdir stages</c>
# <c>mv stage1-x86-1.4_preDATE.tar.bz2 /usr/src/build/stager/stages</c>
# <c>cd /usr/src/grp/stager; mkdir stages </c>
# <c>mv stage1-x86-1.4_pre20030214.tar.bz2 /usr/src/grp/stager/stages </c>

		</pre>

		</body>
	</section>


	<section>
		<title>Building</title>
		<body>
		<p>First, we need to build a stage2 tarball that uses generic optimizations. This tarball
		will be used to build any new fresh stages, including a fresh stage1.
		</p>

		<pre caption="Building stage2">
# <c>./stager x86 2 orig dest</c>
<codenote>Above, orig refers to the date in the name of the experimental tarball. Dest refers to the date of the new tarball. Replace these accordingly.</codenote>		
<codenote>You can change DEST to whatever you desire, but for testing, it is easier to keep it
the same as SOURCE</codenote>
DEST=stage1-x86-1.4_pre20030214.tar.bz2
		</pre>

		<p>Once this build finishes, you should now have a fresh stage2 tarball alongside your original stage1 tarball in the <path>stages</path>
		directory. Now you can build a new stage1 from your stage2 using basically the same method:
		</p>

		<pre caption="Building new stage1">
# <c>./stager x86 1 dest dest</c>
		</pre>
	<section>
		<title>Build!</title>
		<body>

		<p>Tada - you've built a fresh stage1 alongside your original stage1 and new stage2. Now you can build non-generic tarballs that are
		optimized for specific CPU sub-types. Be warned that these optimized tarballs <i>cannot</i> be used to build other stages. Only
		generic tarballs should be used to build other stages. Building for other sub-types is the same - merely replace x86 with the specific sub-type.
		For a list of subtypes, execute stager without any arguments.</p>

		<p>After the build completes, remove the <path>packages</path> and <path>build</path> directories
		from under the stages directory so that you don't get any precompiled packages for a
		different arch in your next build.
		</p>
		
		</body>
	</section>

</chapter>

<chapter>

			<th>Function</th>
		</tr>
		<tr>
			<ti><mail link="avenj@gentoo.org">Jon Portnoy</mail></ti>
			<ti>Gentoo Linux Release Manager</ti>
		</tr>
		<tr>
			<ti><mail link="jhhudso@gentoo.org">Jared Hudson</mail></ti>
			<ti>Release quality assurance</ti>
		</tr>
		<tr>
			<ti><mail link="zhen@gentoo.org">John Davis</mail></ti>
			<ti>Author</ti>
		</tr>
		<tr>
			<ti><mail link="avenj@gentoo.org">Jon Portnoy</mail></ti>
			<ti>Author</ti>
		</tr>
		</table>
		

Return to bug 22711

Lines 2-31 Link Here

(-)/home/avenj/gentoo/build/gentoo/xml/htdocs/doc/en/stage-building-guide.xml (-54 / +46 lines)
2	<?xml-stylesheet href="/xsl/guide.xsl" type="text/xsl"?>	2	<?xml-stylesheet href="/xsl/guide.xsl" type="text/xsl"?>
3	<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">	3	<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
4		4
5	<guide link="/doc/en/grp-build.xml">	5	<guide link="/doc/en/stage-building-guide.xml">
6		6
7	<author title = "Author">	7	<author title = "Author"><mail link = "zhen@gentoo.org">John P. Davis</mail></author>
8	<mail link = "zhen@gentoo.org">John P. Davis</mail></author>	8	<author title = "Author"><mail link = "avenj@gentoo.org">Jon Portnoy</mail></author>
9		9
10	<version>1.0</version>	10	<version>1.1</version>
11	<date>18 Feb 2003</date>	11	<date>12 Jun 2003</date>
12		12
13	<abstract>This guide is an explanation on how to build GRP stages for	13	<abstract>This guide is an explanation on how to build stages for
14	Gentoo Linux releases.</abstract>	14	Gentoo Linux.</abstract>
15		15
16	<chapter>	16	<chapter>
17	<title>Preliminaries</title>	17	<title>Preliminaries</title>
18	<section>	18	<section>
19	<title>Introduction</title>	19	<title>Introduction</title>
20	<body>	20	<body>
21	<p>This guide is an explanation on how to build release-ready	21	<p>This guide is an explanation on how to build fresh
22	GRP stages for Gentoo Linux. This guide assumes a couple of	22	stages for Gentoo Linux using stager, our stage-building application.</p>
23	things: </p>
24
25	<ul>
26	<li>You are a Gentoo Linux Developer.</li>
27	<li>You have access to the <i>gentoo-src</i> module of CVS.</li>
28	</ul>
29		23
30	</body>	24	</body>
31	</section>	25	</section>
Lines 35-43 Link Here
35	<p>Before building anything, it is necessary to get the required source, tools, etc.	29	<p>Before building anything, it is necessary to get the required source, tools, etc.
36	First of all, make sure that you have the <i>gentoo-src</i> module checked out of CVS	30	First of all, make sure that you have the <i>gentoo-src</i> module checked out of CVS
37	and that it is up to date. The build scripts change frequently, so make sure that you stay current.	31	and that it is up to date. The build scripts change frequently, so make sure that you stay current.
		32	If you do not have access to the gentoo-src module, a snapshot of stager can be found at
		33	<uri>http://cvs.gentoo.org/~avenj/stager/</uri>.
38	Additionally, the most recent experimental stage1 tarball is	34	Additionally, the most recent experimental stage1 tarball is
39	required. This can	35	required. This can usually be found at <path>experimental/x86/stages</path> on any Gentoo mirror. The tarball that you will be looking for is
40	usually be found at <uri>http://www.ibiblio.org/gentoo/experimental/x86/stages</uri>. The tarball that you will be looking for is <i>stage1-x86-1.4_pre<i>DATE</i></i>.tar.bz2, where <i>DATE</i> is the most current date possible.	36	<i>stage1-x86-1.4_pre<i>DATE</i></i>.tar.bz2, where <i>DATE</i> is the most recent date available.
41	</p>	37	</p>
42		38
43	</body>	39	</body>
Lines 49-111 Link Here
49	<section>	45	<section>
50	<title>First Steps</title>	46	<title>First Steps</title>
51	<body>	47	<body>
52	<p>First, create a directory on a nice big partition to hold all of the build stuffs. I created mine	48	<p>First, create a directory on a nice big partition to hold all of the build files. Next, copy the <path>stager</path>
53	in <path>/usr/src/grp</path>, but of course, yours can be different. Next, copy the <path>stager</path>
54	directory from <i>gentoo-src</i> into this new	49	directory from <i>gentoo-src</i> into this new
55	directory. Finially, create a directory inside of the <path>grp/stager</path> drive called <i>stages</i>	50	directory (which will be referred to as <path>/usr/src/build</path> in this document). Alternatively, extract the tarball of the snapshot into this directory.
		51	Finially, create a directory inside <path>/usr/src/build</path> called <i>stages</i>
56	and put the experimental stage1 tarball in there.	52	and put the experimental stage1 tarball in there.
57	</p>	53	</p>
58		54
59	<pre caption="Getting Ready">	55	<pre caption="Getting Ready">
60	# <c>mkdir /usr/src/grp </c>	56	# <c>mkdir /usr/src/build </c>
61	<codenote>You can change the above drive to whatever you want, but I will	57	<codenote>You can change the above path to whatever you want.</codenote>
62	reference it as what I have written.	58
63	</codenote>	59	# <c>cp -R /gentoo-src/stager/ /usr/src/build</c>
64		60	# <c>cd /usr/src/build/stager ; mkdir stages</c>
65	# <c>cp -R /<comment>path-to-gentoo-src</comment>/stager/ /usr/src/grp </c>	61	# <c>mv stage1-x86-1.4_preDATE.tar.bz2 /usr/src/build/stager/stages</c>
66	# <c>cd /usr/src/grp/stager; mkdir stages </c>
67	# <c>mv stage1-x86-1.4_pre20030214.tar.bz2 /usr/src/grp/stager/stages </c>
68		62
69	</pre>	63	</pre>
70		64
71	</body>	65	</body>
72	</section>	66	</section>
73		67
		68
74	<section>	69	<section>
75	<title>Pre-Build Configuration</title>	70	<title>Building</title>
76	<body>	71	<body>
77	<p>Once everything is in the correct place, modify the <c>dostage.sh</c> script to fit your application.	72	<p>First, we need to build a stage2 tarball that uses generic optimizations. This tarball
		73	will be used to build any new fresh stages, including a fresh stage1.
78	</p>	74	</p>
79		75
80	<pre caption="Modifying the dostage.sh script">	76	<pre caption="Building stage2">
81	<codenote>change SOURCE to stage1-x86-1.4_preFOO</codenote>	77	# <c>./stager x86 2 orig dest</c>
82	SOURCE=stage1-x86-1.4_pre20030214.tar.bz2	78	<codenote>Above, orig refers to the date in the name of the experimental tarball. Dest refers to the date of the new tarball. Replace these accordingly.</codenote>
83	<codenote>You can change DEST to whatever you desire, but for testing, it is easier to keep it
84	the same as SOURCE</codenote>
85	DEST=stage1-x86-1.4_pre20030214.tar.bz2
86	</pre>	79	</pre>
87		80
88	<p>After that is complete, make sure to change the m/arch in the for loop to match your architecture.	81	<p>Once this build finishes, you should now have a fresh stage2 tarball alongside your original stage1 tarball in the <path>stages</path>
		82	directory. Now you can build a new stage1 from your stage2 using basically the same method:
89	</p>	83	</p>
90		84
91	</body>	85	<pre caption="Building new stage1">
92	</section>	86	# <c>./stager x86 1 dest dest</c>
93		87	</pre>
94	<section>
95	<title>Build!</title>
96	<body>
97		88
98	<p>Make sure that you are root, and run <c>dostage.sh</c>. The script will take care of creating	89	<p>Tada - you've built a fresh stage1 alongside your original stage1 and new stage2. Now you can build non-generic tarballs that are
99	the chroot environment, and it will build all of the stages for you.	90	optimized for specific CPU sub-types. Be warned that these optimized tarballs <i>cannot</i> be used to build other stages. Only
100	</p>	91	generic tarballs should be used to build other stages. Building for other sub-types is the same - merely replace x86 with the specific sub-type.
		92	For a list of subtypes, execute stager without any arguments.</p>
101		93
102	<p>After the build completes, remove the <path>packages</path> and <path>build</path> directories
103	from under the stages directory so that you don't get any precompiled packages for a
104	different arch in your next build.
105	</p>
106
107	</body>	94	</body>
108	</section>	95	</section>
		96
109	</chapter>	97	</chapter>
110		98
111	<chapter>	99	<chapter>
Lines 120-135 Link Here
120	<th>Function</th>	108	<th>Function</th>
121	</tr>	109	</tr>
122	<tr>	110	<tr>
123	<ti><mail link="bcowan@gentoo.org">Brad Cowan</mail></ti>	111	<ti><mail link="avenj@gentoo.org">Jon Portnoy</mail></ti>
124	<ti>Gentoo Linux Release Manager</ti>	112	<ti>Gentoo Linux Release Manager</ti>
125	</tr>	113	</tr>
126	<tr>	114	<tr>
127	<ti><mail link="jhhudso@gentoo.org">Jared Hudson</mail></ti>	115	<ti><mail link="jhhudso@gentoo.org">Jared Hudson</mail></ti>
128	<ti>Stage Builds</ti>	116	<ti>Release quality assurance</ti>
129	</tr>	117	</tr>
130	<tr>	118	<tr>
131	<ti><mail link="zhen@gentoo.org">John Davis</mail></ti>	119	<ti><mail link="zhen@gentoo.org">John Davis</mail></ti>
132	<ti>Documentation Coordinator/ Author</ti>	120	<ti>Author</ti>
		121	</tr>
		122	<tr>
		123	<ti><mail link="avenj@gentoo.org">Jon Portnoy</mail></ti>
		124	<ti>Author</ti>
133	</tr>	125	</tr>
134	</table>	126	</table>
135		127