CVS: src/si/docs README,1.8,1.9

Update of /cvsroot/lsb/src/si/docs
In directory sc8-pr-cvs1:/tmp/cvs-serv12260

Modified Files:
	README 
Log Message:
Update, pass 1


Index: README
===================================================================
RCS file: /cvsroot/lsb/src/si/docs/README,v
retrieving revision 1.8
retrieving revision 1.9
diff -C2 -r1.8 -r1.9
*** README	29 Aug 2002 18:06:56 -0000	1.8
--- README	15 Jan 2003 21:10:30 -0000	1.9
***************
*** 2,7 ****
  
  This package contains the components to build a sample implementation of the
! Linux Standards Base (LSB) version 1.2.  It is built using the Linux From
! Scratch (LFS) project's build system as a starting point.  The goal of this
  sample implementation is to create a minimal system which contains only items
  required by the LSB.  The hope is that other groups can then use this minimal
--- 2,7 ----
  
  This package contains the components to build a sample implementation of the
! Linux Standards Base (LSB) version 1.2 and later.  It is built using the Linux
! From Scratch (LFS) project's build system as a starting point.  The goal of this
  sample implementation is to create a minimal system which contains only items
  required by the LSB.  The hope is that other groups can then use this minimal
***************
*** 17,79 ****
  about the test suite.
  
  Build Information:
  
! In order to get started with the LSBsi you need to first build src/tools/nALFS
! from LSB cvs, download the set of source bundles, and then run the entitycheck
! script.
  
! From within the si directory running 'make nALFS' will build the tool once you
! have checked it out from cvs.
  
  $ pwd
! /home/shaleh/lsb
! $ cvs co src/tools/nALFS
  $ cd src/si
! $ make nALFS
! 
! Next up you need to retrieve the packages that form the LSBsi, these can be
! obtained from:
  
! ftp://ftp.freestandards.org/pub/lsb/impl/beta/source
! 
! You are looking for files name lsbsi-patches-<date>.tar.gz and
! lsbsi-packages-<date>.tar.  The dates need not match but be sure to get the
! latest version available.
! 
! Once the file is downloaded, make a directory somewhere on your system.  The
! location where the LSBsi build expects to find the sources is
! /usr/src/packages/LFS/packages-3.2 but this can be changed by running the
! Configure script found in the LSBsi's top level directory.  From within the
! new source directory:
! 
! $ tar xvf /path/to/lsbsi-packages-08282002.tar
! 
! This will give you all of the sources and patches required to build the si. 
! 
! Return to the LSBsi's top level directory and run extras/entitycheck.py.  This
! utility verifies that you have all of the sources required to build the LSBsi.
! If a package is missing you will not find out until partially through the
! build and that will mean an hour or two of wasted time.  entitycheck is a
! simple script which takes two arguments -- the entity file listing the packages
! needed (entities/package) and the path to the sources you downloaded above.
! A sample run looks like:
! 
! $ cd src/si/extras
! $ ./entitycheck.py ../entities/package /usr/src/LSB/packages/
! Package entities found: 54
! Patch entities found: 14
! 
! If any files are missing or if extra files are found the script will list
! the file name(s).  This both ensures you have everything needed and prevents
! the accumulation of cruft as the packages change.
! 
! Next run the Configure script in the top level of the si.  This will ask for
! the location of the sources as well as where to build the si and its
! components.  There is a little intelligence in the script but not much.  It
! will detect missing directories or warn you of existing si pieces but not much
! else.
  
  Once this is done, you can either execute 'nALFS LSB.xml' or run 'make' --
! either must be done as root. This will create the si rooted at /mnt/lsbsi by
  default, you can also change this with the Configure script as noted above.
  nALFS will provide a curses based interface whereas the makefile will run nALFS
--- 17,95 ----
  about the test suite.
  
+ Note: a quickstart recipe is available on the web page
+ http://www.linuxbase.org/impl/build.html.  If all you want to do is compile
+ the sample, that may be the place to start.
+ 
  Build Information:
  
! In order to get started with the LSBsi you need to build src/tools/nALFS
! from LSB cvs, download the set of source bundles, and run the entitycheck
! script to make sure everything is in place.  As of version 1.3 of the
! sample, the entitycheck script can handle downloading the source bundles.
! 
! From within the si directory running 'make nalfs' will build the tool once you
! have checked it out from cvs. 
  
! If you only want to check out a snapshot for building, and don't plan to
! commit changes back into the cvs tree, 'cvs export' should serve fine:
  
  $ pwd
! /home/shaleh
! $ mkdir LSB
! $ cd LSB
! $ cvs -d :pserver:[email protected]:/cvsroot/lsb export -D now src/si
! $ cvs -d :pserver:[email protected]:/cvsroot/lsb export -D now tools/nALFS
  $ cd src/si
! $ ./Configure
! ... answer the questions ...
! $ make nalfs
! 
! Next up you need to retrieve the packages that form the LSBsi.
! For each entity that describes a package, there's a matching
! line in the extras/package_locations file that describes where
! to find the package, and optionally an alternate location if
! the main location is likely to change.  Stable, official locations
! are used when possible, the "likely to change" comes in when
! the website follows a policy of moving an older release to
! a different location when a new one comes out.  The entitycheck
! tool can retrieve the packages if it's able to speak ftp and
! http without being stopped by your firewall (see below for a
! quick note on using a proxy).  The entitycheck tool can also
! check a file of checksums (extras/md5sums) for further verification
! that you have the right bits.
! 
! $ make update
! (runs entitycheck to retrieve packages)
! 
! You may need to do this as root depending on the permissions
! you set on the package directory you specified to Configure.
! 
! 
! Proxy note:
! 
! entitycheck uses the Python urllib library to retrieve packages.
! This library can try to use a proxy for the http and ftp services.
! If you need to use a proxy, first set 'http_proxy' and 'ftp_proxy'
! in the environment, using the form: xxx_proxy=host:port
! 
! 
! Next, you'll need to move the required patches to the package directory.
! The entitychecker does not retrieve those since you already have them:
! they're in the src/si/patches directory.  Copy those to the package
! directory.
! 
! Return to the LSBsi's top level directory and run extras/entitycheck.py
! one more time.  The resulting report will tell you about any missing
! entities.  If you use the makefile to drive the build, it will run
! the entitychecker before starting, and refuse to proceed if there
! are any problems. Otherwise, if a package is missing you will not find
! out until partially through the build and that may mean many hours
! of wasted time.
  
! $ cd ~/LSB/src/si
! $ extras/entitycheck.py -c
  
  Once this is done, you can either execute 'nALFS LSB.xml' or run 'make' --
! either must be done as root. This will create the si rooted at /usr/src/si by
  default, you can also change this with the Configure script as noted above.
  nALFS will provide a curses based interface whereas the makefile will run nALFS
***************
*** 87,107 ****
  
  Note, the build started with LSB.xml will take roughly 3 hours on a 1.7ghz
! P4, consume around a gigabyte of disk space, and in general swamp the machine.
! Find a beefy machine you can ignore for a while as it churns.  If the build
! fails for some reason run 'mount' and find all of the bind mounts nALFS left
! open and close them.  This is usually an extra /proc and the packages mount.
  Then remove the build directory using the path you specified to Configure and
! start again.  That's right, all over (-:  As you become familiar with the
! system you will discover places that are safe to restart from but in the
! beginning just starting fresh is best.  Hopefully this process will become
! more fault tolerant and require less manual control over time.
! 
! Once you have successfully built the LSBsi parts of the build process are left
! behind and can be reused thus reducing the edit/build/test cycle.
! The LSB.phase3.xml file defines how to build just the si and can be used after
! the initial build has completed if changes were only made to phase3.  Typing
! 'make lsbsi' in the top level directory will do just that.
  
  Enjoy a cup (or 3) of your favorite beverage while the system is building ....
  
  Design Information:
--- 103,147 ----
  
  Note, the build started with LSB.xml will take roughly 3 hours on a 1.7ghz
! P4, consume over a gigabyte of disk space, and in general swamp the machine.
! Find a beefy machine you can ignore for a while as it churns.  On slower
! machines, with less memory, the full build has been known to take 20 hours!
! 
! If the build fails for some reason run 'mount' and find all of the bind
! mounts nALFS left open and close them.  This is usually an extra /proc
! and the packages mount.  There's a makefile target to help with this, try
! 
! # make clear_mounts
! 
  Then remove the build directory using the path you specified to Configure and
! start again.  That's right, all over (-:  There's another make target:
! 
! # make scrub
! 
! Actually, the build is mostly restartable in benign cases, that is, if
! your machine crashes or you have to kill the build or something.  But if
! there was a problem and you're not really sure what caused it, like, say,
! something doesn't compile and it could be the compiler you build earlier,
! then it's by far safer to blow the whole build area away and start over.
! 
! Once you have successfully built the LSBsi parts of the build process are
! left behind and can be reused thus reducing the edit/build/test cycle.
! The LSB.phase3.xml file defines how to build just the si and can be used
! after the initial build has completed if changes were only made to phase3.
! Typing 'make lsbsi' in the top level directory will do just that.  The build
! tool leaves a stamp file behind after each major package is built, and the
! makefile leaves a stamp file behind as each phase is completed.  This is one
! of the main restartability features, but there's a downside:  if you *know*
! you want to rebuild a specific package and it doesn't affect anything else
! (i.e., you don't need to resort to "make scrub"), it won't rebuild because the
! stamp file will prevent it.  You'll have to rub out the stamp file to proceed.
! 
! The bootstrap phase puts the stamp files in /tmp.  The other phases run
! in a chroot environment, so the stamps go inside that chroot - in fact,
! they go in the /tmp inside the chroot, so by default they would be in
! /usr/src/si/lsbsi-intermediate/tmp.  The filenames are easy to recognize
! once you find the directory.
  
  Enjoy a cup (or 3) of your favorite beverage while the system is building ....
+ 
  
  Design Information: