Author: dlichteblau Date: Sun May 28 10:27:42 2006 New Revision: 5
Added: trunk/steeldump-web/building.html Modified: trunk/steeldump-web/index.html Log: moved development instruction to their own page added version numbers
Added: trunk/steeldump-web/building.html ============================================================================== --- (empty file) +++ trunk/steeldump-web/building.html Sun May 28 10:27:42 2006 @@ -0,0 +1,261 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"> + <head> + <title>Steeldump</title> + <link rel="stylesheet" type="text/css" href="steeldump.css"/> + </head> + <body> + <div class="sidebar"> + <div class="sidebar-title"> + about steeldump + </div> + <div class="sidebar-main" style="padding-bottom: 1px"> + <ul> + <li> + <a href="index.html">Main page:</a> + <ul class="sub"> + <li><a href="index.html#installation">Installation</a></li> + <li><a href="index.html#usage">Usage</a></li> + <li><a href="index.html#bugs">How to report problems</a></li> + </ul> + Development: + <ul class="sub"> + <li><a href="building.html">Building Steeldump</a></li> + <li><a href="#extending">Extending Steeldump</a></li> + </ul> + </li> + <li> + <a href="http://common-lisp.net/cgi-bin/mailman/listinfo/steeldump-devel"> + steeldump-devel@common-lisp.net + </a> + </li> + <li> + <a href="http://common-lisp.net/websvn/listing.php?repname=steeldump&path=%2F&sc=0"> + Browse SVN + </a> + </li> + </ul> + </div> + </div> + + <h1>Steeldump<sub style="font-weight: normal; font-size: 10pt; color: #009c00">BETA</sub></h1> + + <h3> + Building Steeldump + <a name="building"></a> + </h3> + <p> + (You can skip this section if you just want to use steeldump + packages normally. See above for installation instructions.) + </p> + <p> + To help debugging or developing Steeldump, the following steps + should be enough to build your own steeldump packages: + </p> + <ul> + <li> + Set up a chroot environment or virtual machine to compile + steeldump in. + <br/> + <br/> + If you really do not want to do this, keep this in mind: + Steeldump <i>must</i> be compiled in the exact same location + where it is going to be installed into, + <tt>/opt/steeldump</tt>. So you cannot run the steeldump + scripts in a filesystem where steeldump packages are already + installed. + <br/> + <br/> + Although it does not address safety issues, you can obviously + build a mock-up chroot very easily using <tt>mount -o bind</tt>, + so this should not be too much of an issue. + </li> + <li> + Create a new directory <tt>/opt/steeldump</tt>. In the build + environment, this directory should be owned by a non-root user. + (The build scripts will only run <tt>sudo</tt> briefly for each + package to fix file ownership before packaging the files up. + Building should be done normally under your non-root account.) + </li> + <li> + Check out the steeldump scripts from Subversion: + <pre>$ cd /opt/steeldump +$ svn co svn://common-lisp.net/project/steeldump/svn/trunk/scripts</pre> + </li> + <li> + Run the first script: + <pre>/opt/steeldump$ ./scripts/init</pre> + -- or just look at what it does. It merely creates a few + directories and checks whether required software is installed. + CMUCL is used for building (you can use the debian-provided + cmucl package), and dpkg-dev tools as well as sudo are needed. + </li> + <li> + The first package you need to download and build is SBCL: + <pre>$ ./scripts/fetch-sbcl +$ ./scripts/build-sbcl +$ ./scripts/makedeb-sbcl</pre> + </li> + </ul> + <p> + Congratulations: If that worked, you have your first .deb package in + <tt>/opt/steeldump/pool</tt>. + </p> + <ul> + <li> + Now you can build the actual steeldumped applications using the + same steps: + <pre>$ ./scripts/fetch-all +$ ./scripts/build-all +$ ./scripts/makedeb-all</pre> + </li> + </ul> + <p> + And that's it. After makedeb-all, you can find all packages in + the <tt>pool</tt> directory. + </p> + <p> + While debugging, however, you will probably want to build + individual packages instead of all in one go: + </p> + <ul> + <li> + For every system, there is a separate <tt>fetch-</tt><i>foo</i> + script. These fetch-scripts do <i>not</i> track dependencies + for you. When not using <tt>fetch-all</tt>, make sure to + download everything you need before trying to build. + </li> + <li> + The <tt>build-</tt><i>foo</i> scripts can be invoked in an + arbitrary order. For example, building climacs will + automatically compile mcclim if it had not been compiled + yet. <i>However</i>, it does not actually create the dumpfile + for mcclim, you will still have to call <tt>build-mcclim</tt> + eventually before you can make its .deb file. + </li> + <li> + Finally, for <tt>makedeb-all</tt> note that it has one advantage + over the individual <tt>makedeb-</tt><i>foo</i> scripts: Before + calling out to the others, <tt>makedeb-all</tt> relocates the + heap files to non-overlapping locations, speeding up loading of + the heap files a little. + </li> + </ul> + <p> + If you got this far and have working packages in + <tt>/opt/steeldump/pool</tt>, send me a postcard. + </p> + + <h3> + Extending Steeldump + <a name="extending"></a> + </h3> + <p> + (You can skip this section if you just want to use steeldump + packages normally. See above for installation instructions.) + </p> + <p> + To add a new package called "blubba", create these files: + </p> + <ul> + <li> + <tt>/opt/steeldump/scripts/fetch-blubba</tt><br/> + This script must put the source code into + <tt>/opt/steeldump/src/blubba</tt>. Remove version numbers from + the directory name, if any.<br/> + Look at the other fetch scripts for ideas. Usually it is enough + to call one of the helper scripts, <tt>aux/fetch-url</tt>, + <tt>aux/fetch-cvs</tt>, or <tt>aux/fetch-svn</tt>. If you have + to patch the source code, this script is the right place to do + that. + </li> + <li> + <tt>/opt/steeldump/scripts/build-blubba</tt><br/> + Usually this script is trivial and just + calls <tt>build-system</tt>. Copy + over <tt>/opt/steeldump/scripts/build-SAMPLE</tt> and change the + system name from "SAMPLESSYTEMNAME" to "blubba". This script + is the right place to call "make" if the system includes C code. + </li> + <li> + <tt>/opt/steeldump/scripts/lisp/build-blubba.lisp</tt><br/> + This Lisp script is less trivial. Starting from the sample file + <tt>/opt/steeldump/scripts/lisp/build-SAMPLE.lisp</tt>, change + the system name from "SAMPLE" to "blubba", but review the + heap dumping logic carefully. The heap dumper needs to be told + about: + <ul> + <li> + The packages that are to be dumped (look out for multiple + defpackage forms). This is the first argument + to <tt>dump-system</tt>. + </li> + <li> + The ASDF systems involved. If the .asd file contains + multiple system definitions, all of them must be listed + manually in the build script. (The <tt>:system</tt> + argument.) + </li> + <li> + The name of the package the .asd files defines and uses. + (The <tt>:system-package</tt> argument.) + </li> + </ul> + You now have a first draft of the dumping script. Beware that + <em>dumping</em> is not the part where things tend to fail, it is the + loading and running of heap files where mistakes show up. The + heuristic used by the heapdumper is that it thinks in terms of + packages. For many systems, you will have to supply more + information than just the package names, because the software + often installs objects into variables contained + in <em>other</em> packages, slots of objects the heap dumper + cannot know about, etc. + <ul> + <li> + Refer to sb-heapdump documentation on the precise logic used + by the dumper. + </li> + <li> + For CLIM systems in particular, application-defined command + tables and presentation types need to be extracted from + McCLIM-internal tables. CLIM also has methods that are + eql-specializing on objects like +flipping-ink+, so we must + guarantee uniqueness of these objects. For details, see + the build scripts for gsharp and climacs. + </li> + <li> + Any CLOS usage can be tricky. The heap dumper will (a) + include generic functions and all their methods in the + package the generic function's name is in (for example, the + MCCLIM package), and (b) additional methods in a different + package if those methods specialize on a class named by a + symbol in that other package (for example, methods defined + for classes in the CLIMACS package). One corollary of these + rules is that we must not dump the McCLIM package after + having loaded Climacs into the same core, because then + loading of McCLIM would fail trying to find the CLIMACS + package. + </li> + </ul> + </li> + <li> + <tt>/opt/steeldump/scripts/descriptions/blubba</tt><br/> + This file ends up as the <tt>Description:</tt> header in the + Debian package's <tt>control</tt> file. + Again there is a skeleton file: + <tt>/opt/steeldump/scripts/descriptions/SAMPLE</tt>. + </li> + <li> + <tt>/opt/steeldump/scripts/makedeb-blubba</tt><br/> + This scripts collect all files to be installed and creates the + .deb archive. Starting + with <tt>/opt/steeldump/scripts/makedeb-SAMPLE</tt>, + replace SAMPLESYSTEMNAME with "blubba", and DEPENDENCIES with other + steeldump packages that "blubba" depends on. Omit the + "steeldump-" prefix and version number, the helper script + inserts those for you. + </li> + </ul> + </body> +</html>
Modified: trunk/steeldump-web/index.html ============================================================================== --- trunk/steeldump-web/index.html (original) +++ trunk/steeldump-web/index.html Sun May 28 10:27:42 2006 @@ -18,8 +18,11 @@ <li><a href="#installation">Installation</a></li> <li><a href="#usage">Usage</a></li> <li><a href="#bugs">How to report problems</a></li> - <li><a href="#building">Building Steeldump</a></li> - <li><a href="#extending">Extending Steeldump</a></li> + </ul> + Development: + <ul class="sub"> + <li><a href="building.html">Building Steeldump</a></li> + <li><a href="building.html#extending">Extending Steeldump</a></li> </ul> </li> <li> @@ -39,9 +42,18 @@ </div> <div class="sidebar-main"> <ul> - <li><a href="http://common-lisp.net/project/beirc">beirc</a></li> - <li><a href="http://common-lisp.net/project/climacs">climacs</a></li> - <li><a href="http://common-lisp.net/project/gsharp">gsharp</a></li> + <li> + <a href="http://common-lisp.net/project/beirc">beirc</a> + <sub> from CVS</sub> + </li> + <li> + <a href="http://common-lisp.net/project/climacs">climacs</a> + <sub> from CVS</sub> + </li> + <li> + <a href="http://common-lisp.net/project/gsharp">gsharp</a> + <sub> from CVS</sub> + </li> </ul> </div> <div class="sidebar-title"> @@ -49,22 +61,55 @@ </div> <div class="sidebar-main"> <ul> - <li><a href="http://weitz.de/cl-fad/">cl-fad</a></li> - <li><a href="http://common-lisp.net/project/cl-irc">cl-irc</a></li> - <li><a href="http://weitz.de/cl-ppcre/">cl-ppcre</a></li> + <li> + <a href="http://weitz.de/cl-fad/">cl-fad</a> + <sub> 0.5.0</sub> + </li> + <li> + <a href="http://common-lisp.net/project/cl-irc">cl-irc</a> + <sub> from SVN</sub> + </li> + <li> + <a href="http://weitz.de/cl-ppcre/">cl-ppcre</a> + <sub> 1.2.14</sub> + </li> <li> <a href="http://common-lisp.net/project/climacs">esa</a> + <sub> from CVS</sub> (<a href="http://www.cliki.net/esa">about</a>) </li> - <li><a href="http://www.cliki.net/CLX">clx</a></li> - <li><a href="http://weitz.de/flexi-streams/">flexi-streams</a></li> - <li><a href="http://common-lisp.net/project/flexichain">flexichain</a></li> - <li><a href="http://common-lisp.net/project/mcclim">McCLIM</a></li> - <li><a href="http://www.cliki.net/spatial-trees">spatial-trees</a></li> - <li><a href="http://www.cliki.net/split-sequence">split-sequence</a></li> + <li> + <a href="http://www.cliki.net/CLX">clx</a> + <sub> 0.7.3</sub> + </li> + <li> + <a href="http://weitz.de/flexi-streams/">flexi-streams</a> + <sub> 0.5.5</sub> + </li> + <li> + <a href="http://common-lisp.net/project/flexichain">flexichain</a> + <sub> from CVS</sub> + </li> + <li> + <a href="http://common-lisp.net/project/mcclim">McCLIM</a> + <sub> from CVS</sub> + </li> + <li> + <a href="http://www.cliki.net/spatial-trees">spatial-trees</a> + <sub> 0.2</sub> + </li> + <li> + <a href="http://www.cliki.net/split-sequence">split-sequence</a> + </li> <li>tab-layout</li> - <li><a href="http://common-lisp.net/project/cl-plus-ssl#trivial-gray-streams">trivial-gray-streams</a></li> - <li><a href="http://www.cliki.net/trivial-sockets">trivial-sockets</a></li> + <li> + <a href="http://common-lisp.net/project/cl-plus-ssl#trivial-gray-streams">trivial-gray-streams</a> + <sub> from CVS</sub> + </li> + <li> + <a href="http://www.cliki.net/trivial-sockets">trivial-sockets</a> + <sub> 0.3</sub> + </li> </ul> </div> </div> @@ -204,222 +249,5 @@ If, however, the bug is also present is the upstream source code, please send your report directly to the upstream project. Thanks. </p> - - <h3> - Building Steeldump - <a name="building"></a> - </h3> - <p> - (You can skip this section if you just want to use steeldump - packages normally. See above for installation instructions.) - </p> - <p> - To help debugging or developing Steeldump, the following steps - should be enough to build your own steeldump packages: - </p> - <ul> - <li> - Set up a chroot environment or virtual machine to compile - steeldump in. - <br/> - <br/> - If you really do not want to do this, keep this in mind: - Steeldump <i>must</i> be compiled in the exact same location - where it is going to be installed into, - <tt>/opt/steeldump</tt>. So you cannot run the steeldump - scripts in a filesystem where steeldump packages are already - installed. - <br/> - <br/> - Although it does not address safety issues, you can obviously - build a mock-up chroot very easily using <tt>mount -o bind</tt>, - so this should not be too much of an issue. - </li> - <li> - Create a new directory <tt>/opt/steeldump</tt>. In the build - environment, this directory should be owned by a non-root user. - (The build scripts will only run <tt>sudo</tt> briefly for each - package to fix file ownership before packaging the files up. - Building should be done normally under your non-root account.) - </li> - <li> - Check out the steeldump scripts from Subversion: - <pre>$ cd /opt/steeldump -$ svn co svn://common-lisp.net/project/steeldump/svn/trunk/scripts</pre> - </li> - <li> - Run the first script: - <pre>/opt/steeldump$ ./scripts/init</pre> - -- or just look at what it does. It merely creates a few - directories and checks whether required software is installed. - CMUCL is used for building (you can use the debian-provided - cmucl package), and dpkg-dev tools as well as sudo are needed. - </li> - <li> - The first package you need to download and build is SBCL: - <pre>$ ./scripts/fetch-sbcl -$ ./scripts/build-sbcl -$ ./scripts/makedeb-sbcl</pre> - </li> - </ul> - <p> - Congratulations: If that worked, you have your first .deb package in - <tt>/opt/steeldump/pool</tt>. - </p> - <ul> - <li> - Now you can build the actual steeldumped applications using the - same steps: - <pre>$ ./scripts/fetch-all -$ ./scripts/build-all -$ ./scripts/makedeb-all</pre> - </li> - </ul> - <p> - And that's it. After makedeb-all, you can find all packages in - the <tt>pool</tt> directory. - </p> - <p> - While debugging, however, you will probably want to build - individual packages instead of all in one go: - </p> - <ul> - <li> - For every system, there is a separate <tt>fetch-</tt><i>foo</i> - script. These fetch-scripts do <i>not</i> track dependencies - for you. When not using <tt>fetch-all</tt>, make sure to - download everything you need before trying to build. - </li> - <li> - The <tt>build-</tt><i>foo</i> scripts can be invoked in an - arbitrary order. For example, building climacs will - automatically compile mcclim if it had not been compiled - yet. <i>However</i>, it does not actually create the dumpfile - for mcclim, you will still have to call <tt>build-mcclim</tt> - eventually before you can make its .deb file. - </li> - <li> - Finally, for <tt>makedeb-all</tt> note that it has one advantage - over the individual <tt>makedeb-</tt><i>foo</i> scripts: Before - calling out to the others, <tt>makedeb-all</tt> relocates the - heap files to non-overlapping locations, speeding up loading of - the heap files a little. - </li> - </ul> - <p> - If you got this far and have working packages in - <tt>/opt/steeldump/pool</tt>, send me a postcard. - </p> - - <h3> - Extending Steeldump - <a name="extending"></a> - </h3> - <p> - (You can skip this section if you just want to use steeldump - packages normally. See above for installation instructions.) - </p> - <p> - To add a new package called "blubba", create these files: - </p> - <ul> - <li> - <tt>/opt/steeldump/scripts/fetch-blubba</tt><br/> - This script must put the source code into - <tt>/opt/steeldump/src/blubba</tt>. Remove version numbers from - the directory name, if any.<br/> - Look at the other fetch scripts for ideas. Usually it is enough - to call one of the helper scripts, <tt>aux/fetch-url</tt>, - <tt>aux/fetch-cvs</tt>, or <tt>aux/fetch-svn</tt>. If you have - to patch the source code, this script is the right place to do - that. - </li> - <li> - <tt>/opt/steeldump/scripts/build-blubba</tt><br/> - Usually this script is trivial and just - calls <tt>build-system</tt>. Copy - over <tt>/opt/steeldump/scripts/build-SAMPLE</tt> and change the - system name from "SAMPLESSYTEMNAME" to "blubba". This script - is the right place to call "make" if the system includes C code. - </li> - <li> - <tt>/opt/steeldump/scripts/lisp/build-blubba.lisp</tt><br/> - This Lisp script is less trivial. Starting from the sample file - <tt>/opt/steeldump/scripts/lisp/build-SAMPLE.lisp</tt>, change - the system name from "SAMPLE" to "blubba", but review the - heap dumping logic carefully. The heap dumper needs to be told - about: - <ul> - <li> - The packages that are to be dumped (look out for multiple - defpackage forms). This is the first argument - to <tt>dump-system</tt>. - </li> - <li> - The ASDF systems involved. If the .asd file contains - multiple system definitions, all of them must be listed - manually in the build script. (The <tt>:system</tt> - argument.) - </li> - <li> - The name of the package the .asd files defines and uses. - (The <tt>:system-package</tt> argument.) - </li> - </ul> - You now have a first draft of the dumping script. Beware that - <em>dumping</em> is not the part where things tend to fail, it is the - loading and running of heap files where mistakes show up. The - heuristic used by the heapdumper is that it thinks in terms of - packages. For many systems, you will have to supply more - information than just the package names, because the software - often installs objects into variables contained - in <em>other</em> packages, slots of objects the heap dumper - cannot know about, etc. - <ul> - <li> - Refer to sb-heapdump documentation on the precise logic used - by the dumper. - </li> - <li> - For CLIM systems in particular, application-defined command - tables and presentation types need to be extracted from - McCLIM-internal tables. CLIM also has methods that are - eql-specializing on objects like +flipping-ink+, so we must - guarantee uniqueness of these objects. For details, see - the build scripts for gsharp and climacs. - </li> - <li> - Any CLOS usage can be tricky. The heap dumper will (a) - include generic functions and all their methods in the - package the generic function's name is in (for example, the - MCCLIM package), and (b) additional methods in a different - package if those methods specialize on a class named by a - symbol in that other package (for example, methods defined - for classes in the CLIMACS package). One corollary of these - rules is that we must not dump the McCLIM package after - having loaded Climacs into the same core, because then - loading of McCLIM would fail trying to find the CLIMACS - package. - </li> - </ul> - </li> - <li> - <tt>/opt/steeldump/scripts/descriptions/blubba</tt><br/> - This file ends up as the <tt>Description:</tt> header in the - Debian package's <tt>control</tt> file. - Again there is a skeleton file: - <tt>/opt/steeldump/scripts/descriptions/SAMPLE</tt>. - </li> - <li> - <tt>/opt/steeldump/scripts/makedeb-blubba</tt><br/> - This scripts collect all files to be installed and creates the - .deb archive. Starting - with <tt>/opt/steeldump/scripts/makedeb-SAMPLE</tt>, - replace SAMPLESYSTEMNAME with "blubba", and DEPENDENCIES with other - steeldump packages that "blubba" depends on. Omit the - "steeldump-" prefix and version number, the helper script - inserts those for you. - </li> - </ul> </body> </html>