[or-cvs] r14845: Thorough update and revision of the building instructions. N (incognito/trunk)

anonym at seul.org anonym at seul.org
Fri May 30 18:01:46 UTC 2008


Author: anonym
Date: 2008-05-30 14:01:46 -0400 (Fri, 30 May 2008)
New Revision: 14845

Modified:
   incognito/trunk/building.html
Log:
Thorough update and revision of the building instructions. Now other people may actually be successful building it themselves.


Modified: incognito/trunk/building.html
===================================================================
--- incognito/trunk/building.html	2008-05-30 12:34:22 UTC (rev 14844)
+++ incognito/trunk/building.html	2008-05-30 18:01:46 UTC (rev 14845)
@@ -5,7 +5,7 @@
 <body>
 
 <p>
-Following are the steps to build the Incognito CD. Note that this process will take a long time as all software is compiled from scratch. You'll get a nice, compact, optimized CD though.
+Following is the requirements and instructions for building the Incognito LiveCD. Note that this process will take a long time as all software is compiled from scratch.
 </p>
 
 <p>
@@ -13,40 +13,57 @@
 <ul>
 <li><a href="http://www.gentoo.org">Gentoo Linux</a> system OR Gentoo Linux chroot environment</li>
 <li><a href="http://packages.gentoo.org/packages/?category=dev-util;name=catalyst">&gt;=catalyst-2.0.4</a></li>
-<li>The Incognito sources should be placed in <code>/usr/src/incognito</code> (this is currently assumed by the build-scripts and spec-files).</li>
+<li>Good understanding of catalyst, portage, Gentoo and Linux systems in general</li>
+<li>The Incognito sources (get them from <a href="https://tor-svn.freehaven.net/svn/incognito/">here</a>) should be placed in <code>/usr/src/incognito</code> (this is currently assumed by the build-scripts and spec-files, unfortunately).</li>
 </ul>
 </p>
 
+<p>Here are the instructions. Note that these are not meant as a step-to-step guide really, but more as a set of pointers. It's assumed that you know what you're doing. If you don't, you might very well fail at some point even if you follow the preceeding steps precisely.</p>
+
 <ol>
 
-<li><p>Pick version number from current date using YYYYMMDD format:</p>
+<li><p>First of all you will need a portage snapshot. This can be done either by using one of the snapshots used for building the official Incognito releases, or by generating your own one that might be more up to date. Usually, if you're using the trunk sources (i.e. the development version) you should generate your own snapshot. Note that generating your own snapshot most likely will require alot more modifications and ebuild hacking to get working. If you're trying to build any of the tagged versions (i.e. any past Incognito release) you might want to get the snapshot for that release (if it's available) since you then avoid the above mentioned trouble.</p>
+
+<p>Choose any <b>one</b> of the following alternatives:</p>
+
+<ol type="a">
+
+<li><p>Download an Incognito portage snapshot from <a href="http://files1.cjb.net/incognito/">the official Incognito download site</a> and place it in <code>/var/tmp/catalyst/snapshots</code>. Note that not all releases have portage snapshots available. Also make sure that the spec files (<code>arch/*/*.spec</code>) have a matching <code>snapshot</code> value.</p>
+
+<li><p>For generating your own snapshot, first pick a version number as the current date using YYYYMMDD format:</p>
 	<pre>
 	YYYYMMDD=$(date +%Y%m%d)
 	</pre>
-</li>
-
-<li><p>Download the latest Incognito portage snapshot from <a href="http://files1.cjb.net/incognito/">the official Incognito download site</a> and place it in <code>/var/tmp/catalyst/snapshots</code>.</p>
-<p>Alternatively you can generate you own portage snapshot that is more up to date, but that will most likely require alot more modifications and ebuild hacking to get working.</p>
+<p>Then sync portage and generate the snapshot:</p>
 	<pre>
 	emerge --sync
 	catalyst -s ${YYYYMMDD}
 	</pre>
-</li>
 
-<li>Update arch/*/*.spec files with new version number. Note that 20080109 or whatever number that's there currently will need to be changed to the current setting in the spec files.
+<p>Update the spec files (<code>arch/*/*.spec</code>) with new version number. You can either do this manually or use something like the command below. Note that the "20080109" below will need to be the same as the version used in the spec files, so you should look it up before issuing the command blindly.</p>
 	<pre>
 	sed -i "s/20080109/${YYYYMMDD}/" arch/*/*.spec
 	</pre>
 </li>
 
-<li>Here there are two path's to go. Either you can generate a stage3 tarball yourself or simply download the one I made. If you have generated your own portage snapshot you probably should generate your own stage1 to stage3, but if your using the snapshots of the current Incognito version you can save time by skipping that step. Choose any <b>one</b> of the following alternatives:
+</ol>
 
+</li>
+
+<li><p>Next you'll need a seed stage, i.e. a stage3, for building the livecd. Here there are two path's to go: Either you can build stage1 to stage3 yourself (which will require several hours of compiling) or you can simply download a stage3 used for some previous Incognito release. If you have generated your own portage snapshot in the previous step you probably should build your own stage1 to stage3. If you instead chose to use the portage snapshot of the some Incognito release you can save time by downloading the stage3 used for building that release.</p>
+
+<p>Choose any <b>one</b> of the following alternatives:</p>
+
 <ol type="a">
 
-<li>Download the current Incognito stage3 tarball from <a href="http://files1.cjb.net/incognito/">the official Incognito download site</a> and place it in <code>/var/tmp/catalyst/build/incognito</code>.</li>
-<li><p>Download an official Gentoo <code>stage3-i686-*.tar.bz2</code> and place it in <code>/var/tmp/catalyst/builds/default/</code>. You can find this tarball on any of <a href=http://www.gentoo.org/main/en/mirrors2.xml>the Gentoo mirrors</a> (choose one that's close to you). The file can usually be found under <code>releases/x86/current/stages/</code>.</p>
+<li>Download the an Incognito stage3 tarball from <a href="http://files1.cjb.net/incognito/">the official Incognito download site</a> and place it in <code>/var/tmp/catalyst/build/incognito</code>. If you're using one of the Incognito releases' snapshots you should download the stage3 of the same date.</p>
 
-<p>Generate stage3 seed stage. After this step any caches in <code>/var/tmp/catalyst</code> related to stage1, stage2 or stage3 may be removed. Only the stage3 tarball needs to be kept.</p>
+<p>Note that you might have to update the <code>source_subpath</code> field in <code>arch/x86/livecd-stage1.spec</code> so that it matches the stage3 you just downloaded.</p>
+</li>
+
+<li><p>To build the stages yourself catalyst will need another stage3 (not to be confused with the one you're going to build) to do the compiling from. Download an official Gentoo <code>stage3-i686-*.tar.bz2</code> (the latest is recommended) and place it in <code>/var/tmp/catalyst/builds/default/</code>. You can find this tarball on any of <a href=http://www.gentoo.org/main/en/mirrors2.xml>the Gentoo mirrors</a> (choose one that's close to you). The file can usually be found under <code>releases/x86/current/stages/</code>.</p>
+
+<p>Generate a stage3 seed stage (stage3 depends on stage1 and stage2, so these will have to be built as intermediate steps). After this step any caches in <code>/var/tmp/catalyst</code> related to stage1, stage2 or stage3 may be removed. Only the stage3 tarball needs to be kept.</p>
 	<pre>
 	./build-stage.sh arch/x86/stage1.spec
 	./build-stage.sh arch/x86/stage2.spec
@@ -56,46 +73,40 @@
 
 </ol>
 
-<li>Generate full version:
+<li><p>Generate livecd-stage1 and the final Incognito LiveCD image:</p>
 	<pre>
 	./build-stage.sh arch/x86/livecd-stage1.spec
 	./livecd-stage2.sh arch/x86/livecd-stage2.spec
 	</pre>
-</li>
 
-<li>Generate tiny version: (currently not under development)
+<p>If you want to build the tiny version (<50 MB, but this is currently not under development or maintained, so YMMV) you should instead do:</p>
 	<pre>
 	./build-stage.sh arch/x86/livecd-stage1-tiny.spec
 	./livecd-stage2.sh arch/x86/livecd-stage2-tiny.spec
 	</pre>
+
+<p>Note that this step will require a lot of CPU intensive compiling, so it could take any where from tens of hours to a couple of days to complete. If you've configured catalyst to use the package cache, only packages whose ebuilds have been updated from the previous time you built them will be rebuilt, which save much time if you want to redo this after the first time.</p>
+
+<p>The image will be saved as <code>/var/tmp/catalyst/build/incognito*/incognito-*.iso</code>.</p>
 </li>
 
 </ol>
 
 <p>
-Updating the Incognito CD with specific software, generally Tor, Polipo, TorK,
-Vidalia, can be done with the following steps:
+Adding software or updating specific packages (generally Tor, Polipo, TorK and Vidalia) can be done with the following steps:
 </p>
 
 <ol>
-<li>Update ebuilds in portage.overlay to desired versions.</li>
-
-<li>Generate full version: (~2 hours)
+<li>Add or update ebuilds in <code>portage.overlay</code> (which uses the same directory hierarchy as <code>/usr/portage</code>). Make sure the manifest files are up to date by running the following command for each new or updated ebuild:
 	<pre>
-	./build-stage.sh arch/x86/livecd-stage1.spec
-	./livecd-stage2.sh arch/x86/livecd-stage2.spec
-	</pre>
+	ebuild /path/to/ebuild manifest
+	</pre>  
 </li>
 
-<li>Generate tiny version: (~30 minutes) (currently not under development)
-	<pre>
-	./build-stage.sh arch/x86/livecd-stage1-tiny.spec
-	./livecd-stage2.sh arch/x86/livecd-stage2-tiny.spec
-	</pre>
+<li>Then re-do the "Generate livecd-stage1 and the final Incognito LiveCD image" step. If the packages you updated or added are installed in livecd-stage2, you only need to redo that part.
 </li>
 
 </ol>
 
 </body>
 </html>
-



More information about the tor-commits mailing list