[or-cvs] r17210: {incognito} Added some clarifications and explanations for what the diff (incognito/trunk)

Fri Nov 7 14:09:07 UTC 2008

Author: anonym
Date: 2008-11-07 09:09:07 -0500 (Fri, 07 Nov 2008)
New Revision: 17210

Modified:
   incognito/trunk/hacking.html
Log:
Added some clarifications and explanations for what the different parts of the sources are for.


Modified: incognito/trunk/hacking.html
===================================================================

--- incognito/trunk/hacking.html	2008-11-07 14:01:44 UTC (rev 17209)
+++ incognito/trunk/hacking.html	2008-11-07 14:09:07 UTC (rev 17210)
@@ -11,7 +11,7 @@
 
 <h2>Pre-reqs</h2>
 
-<p>You must know something about the following technologies:</p>
+<p>First of all you'll need a Linux installation with Catalyst present which probably amounts to a Gentoo installation. If you run another Linux distribution, see below for instructions for setting up a Gentoo Linux chroot. Additionally, you probably should know something about the following technologies to be able to work with Incognito effectively:</p>
 <ul>
 <li>Linux - the base operating system</li>
 <li>Portage - the Gentoo Linux package management system</li>
@@ -19,60 +19,76 @@
 <li>Subversion - the source code management tool</li>
 </ul>
 
-<p>
-Before submitting patches make sure you can build and test the CD. See building.html for build instructions. You can use an emulator/virtualizer such as Qemu, VMWare or Virtual PC to test it.
-</p>
+<p>Before submitting patches, please make sure you can build and run the resulting distribution. See building.html for build instructions. You can use an emulator/virtualizer such as Qemu, VMWare or Virtual PC to test it.</p>
 
 <h2>TODO list</h2>
 If you want to help out, check if there's anything interesting in the <a href="https://tor-svn.freehaven.net/svn/incognito/trunk/TODO">TODO list</a> to design or implement. It might be a good idea to send the developers an email first, checking if there already has been some unannounced progress made etc.
 
-<h2>Updating Packages</h2>
+<h2>Important files and directories</h2>
 
-<p>Updating packages happens in portage.overlay. The following steps with bump the version number. Anything more indepth you'll need to learn how ebuilds work.</p>
-<ol>
-<li>cd to portage.overlay/category/package</li>
-<li>svn mv package-version.ebuild package-newversion.ebuild</li>
-<li>svn rm files/digest-package-version</li>
-<li>ebuild package-newversion.ebuild manifest</li>
-</ol>
+<h3>arch/x86/stage{1,2,3}.spec</h3>
+<p>Specification for the stage 1-3 tarballs. Don't change these unless you really know what you are doing.</p>
 
-<p>
-<strong>NOTICE</strong>: No alpha or beta packages unless absolutely necessary! First, people are recording this to a CD or USB, they cannot easily update to the next alpha if something goes wrong. Second, people are counting on anonymity, the packages should be well tested.
-</p>
+<h3>arch/x86/livecd-stage1{,-tiny}.spec</h3>
+<p>Specification for the main CD build. This gives the packages and use flags that are desired. Do not add packages that depend on the kernel sources being installed, that goes in <code>livecd-stage2.spec</code>.</p>
 
-<h2>Important Files</h2>
+<h3>arch/x86/livecd-stage2{,-tiny}.spec</h3>
+<p>Specification for the final stage which produces the final ISO image. livecd-stage2 basically takes on from livecd-stage1, adds a boot loader, compiles the kernel and packages depending on the kernel, runs <code>fsscript.sh</code> (see below), removes unnecessary packages and files, etc. Most changes will have to do with livecd-stage2 and mostly you can rebuild this stage to test your changes.</p>
 
-<dl>
+<h3>arch/x86/isolinux-*-cdtar.tar.bz2</h3>
+<p>Files for the isolinux boorloader, includung the theme (<code>isolinux/splash.png</code>).</p>
 
-<dt>arch/x86/stage{1,2,3}.spec</dt>
-<dd>
-Specification for the stage 1-3 tarballs. Don't change these unless you really know what you are doing.
-</dd>
+<h3>arch/x86/overlay</h3>
+<p>As per standard Catalyst behaviour, this is the CD overlay. Everything in here will be copied to the root of the ISO image. Of particular interest here is the configuration file for the bootloader (<code>arch/x86/overlay/isolinux/isolinux.cfg</code>).</p>
 
-<dt>arch/x86/livecd-stage1{,-tiny}.spec</dt>
-<dd>
-Specification for the main CD build. This gives the packages and use flags that are desired. Do not add packages that depend on the kernel sources being installed, that goes in livecd-stage2.spec.
-</dd>
+<h3>fsscript.sh</h3>
+<p>This script is run in the chroot environment of livecd-stage2. Look at it to see some things you might need to do.</p>
 
-<dt>arch/x86/livecd-stage2{,-tiny}.spec</dt>
-<dd>
-Specification for the final stage of the CD build. livecd-stage2 basically takes livecd-stage1 and modifies it for use on a live CD. The kernel is built, packages depending on the kernel are installed, package configuration is done, unnecessary packages and files removed, etc. Most changes will have to do with livecd-stage2 and mostly you can rebuild this stage to get your changes.
-</dd>
+<h3>build-stage.sh</h3>
+<p>This scripts is used to build stage{1,2,3}.spec and livecd-stage1.spec, making them directory independent (the spec files use absolute paths to determine the overlays etc.).</p>
 
-<dt>fsscript.sh</dt>
-<dd>
-This script is run in the chroot environment of livecd-stage2. Look at it to see some things you might need to do.
-</dd>
+<h3>livecd-stage2.sh</h3>
+<p>This script does pre-processing for livecd-stage2{,-tiny}.spec. If you need to generate files for the overlay programatically, this is the place to do it.</p>
 
-<dt>livecd-stage2.sh</dt>
-<dd>
-This script does pre-processing for livecd-stage2{,-tiny}.spec. If you need to generate files for the overlay programatically, this is the place to do it.
-</dd>
+<h3>portage.overlay</h3>
+<p>This will act like a normal Portage overlay.</p>
 
-</dl>
+<h3>portage.config</h3>
+<p>This will be copied into <code>/etc/portage</code>, so set package specifig keywords, {un}maskings and USE-flags here.</p>
 
+<h3>root_overlay</h3>
+<p>As per standard Catalyst behaviour, this is the root overlay. This directory structure will be copied into the filesystem root in livecd-stage2, which is very practical for putting custom configs in their right place. Below are described some special files and directories in the root overlay which are put there simply to be accessible for <code>fsscript.sh</code></p>
+
+<h4>root_overlay/etc/init.d/</h4>
+<p>There are some special init scripts here for setting up locale as chosen in the boot menu, creating/mounting a persistent home directory etc.</p>
+
+<h4>root_overlay/usr/{,s}bin</h4>
+<p>All incognito specific scripts are stored here.</p>
+
+<h4>root_overlay/var/patches</h4>
+<p>All patches (<code>*.patch</code>) in this directory are applied to the filesystem root. It is preferrable to use this approach to smaller changes or additions to scripts or configs compared to overlay them with a complete file using the root overlay since that will need constant attention when the responsible packages are updated.</p>
+
+<h4>root_overlay/var/lib/*-config and root_overlay/var/lib/kdesession</h4>
+<p>These are the users' application configs, e.g. <code>firefox-config</code> will be copied to<code>~/.mozilla</code>. The contents of <code>kdesession</code> will be copied into <code>~/kde/share/config</code>.</p>
+
+<h4>root_overlay/var/lib/incognito-menu</h4>
+<p>Used for the Incognito KDE menu.</p>
+
+<h2>Updating packages</h2>
+
+<p>Updating packages happens in <code>portage.overlay</code> (or by updating the portage snapshot, but that's restricted and coordinated by the main developers). The following steps with bump the version number. Anything more indepth you'll need to learn how ebuilds work.</p>
+<ol>
+<li>cd portage.overlay/category/package</li>
+<li>svn mv package-version.ebuild package-newversion.ebuild</li>
+<li>svn rm files/digest-package-version</li>
+<li>ebuild package-newversion.ebuild manifest</li>
+</ol>
+
+<p><strong>NOTICE</strong>: No alpha or beta packages unless absolutely necessary! First, people are recording this to a CD or USB, they cannot easily update to the next alpha if something goes wrong. Second, people are counting on anonymity, the packages should be well tested.</p>
+
+
 <h2>Gentoo Linux chroot environment</h2>
-<p>If you run another Linux distribution than Gentoo Linux (or if you run Gentoo Linux on another arch than x86 or amd64) but want to build Incognito with catalyst, simply fetch a x86 stage-3 tarball from a <a href="http://www.gentoo.org/main/en/mirrors.xml">Gentoo Mirror</a> (preferably the latest release), extract and chroot into it. When inside the chroot, sync portage, update and install relevant applications:</p>
+<p>If you run another Linux distribution than Gentoo Linux but want to build Incognito with Catalyst, simply fetch a x86 stage-3 tarball from a <a href="http://www.gentoo.org/main/en/mirrors.xml">Gentoo Mirror</a> (preferably the latest release), extract and chroot into it. When inside the chroot, sync portage, update and install relevant applications:</p>
 <p><code># get a stage3 tarball<br>
 wget http://files1.cjb.net/incognito/stage3-i686-*.tar.bz2
 <br>
@@ -88,11 +104,7 @@
 emerge -auvDN world<br>
 emerge -av catalyst # some more might be needed</code></p>
 <p>Then use this chroot enivonment as you would use a regular Gentoo Linux installation for building Incognito.</p>
-<p>When using menuconfig for kernel configurations on a different arch than x86, use <code>linux32 make menuconfig</code> (linux32 can be found in the sys-apps/util-linux portage package) to make sure to get a sane kernel config.
+<p>When using menuconfig for kernel configurations on a different arch than x86, use <code>linux32 make menuconfig</code> (linux32 can be found in the sys-apps/util-linux portage package) to make sure to get a sane kernel config.</p>
 
-<h2>Misc</h2>
-
-<p>The arch/*.pyo files are generated by catalyst, I don't know why. Ignore them.</p>
-
 </body>
 </html>

