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

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

Modified Files:
	README 
Log Message:
Pass 2 at updating


Index: README
===================================================================
RCS file: /cvsroot/lsb/src/si/docs/README,v
retrieving revision 1.9
retrieving revision 1.10
diff -C2 -r1.9 -r1.10
*** README	15 Jan 2003 21:10:30 -0000	1.9
--- README	15 Jan 2003 22:00:15 -0000	1.10
***************
*** 21,24 ****
--- 21,25 ----
  the sample, that may be the place to start.
  
+ =============================================================================
  Build Information:
  
***************
*** 45,89 ****
  $ 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
--- 46,87 ----
  $ 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
***************
*** 145,148 ****
--- 143,147 ----
  
  
+ =============================================================================
  Design Information:
  
***************
*** 151,155 ****
  guide for those who want to modify the system for some reason.
  
! First up are the 3 top level xml files which control the build process.
  
  LSB.bootstrap.xml builds only the bootstrap phase. This creates a small chroot
--- 150,154 ----
  guide for those who want to modify the system for some reason.
  
! First up are the several top level xml files which control the build process.
  
  LSB.bootstrap.xml builds only the bootstrap phase. This creates a small chroot
***************
*** 171,174 ****
--- 170,183 ----
  and not fix or tweak anything this is the command for you.
  
+ LSB.phase4.xml builds three add-on packages that can be layered on top of
+ a finished sample implementation to tune it for particular uses.  These are
+ internally described as sub-phases 4a, 4b and 4c.  They support running the
+ LSB runtime test suite; building a bootable system; and running a system
+ that can be run in user-mode Linux, respectively.  LSB.xml does *not* run
+ phase4 at this writing, it must be invoked separately.
+ 
+ make targets support each of the above builds, and can be easily identified
+ by scanning the makefile.
+ 
  If you plan to do any hacking on these files be sure to build the foundation
  phases and then only build the phase you need.  This saves anywhere from 30
***************
*** 181,185 ****
  you of any files in the repository which are not used so cruft does not build.
  It is fairly self documenting (yeah famous last words) and should be easy to
! modify if the need arises.
  
  entities/ contains common variables used by the rest of the system.  If you
--- 190,199 ----
  you of any files in the repository which are not used so cruft does not build.
  It is fairly self documenting (yeah famous last words) and should be easy to
! modify if the need arises, if you know a bit of Python.  If not, this
! script may be your intro to a wonderful new language :-) It's got some extra
! bells and whistles, including the ability to generate a new checksum file
! matching the current set of entities, check checksums against an existing
! file (also found in the extras directory), and retrieve missing or out
! of date packages, as discussed earlier in this document.
  
  entities/ contains common variables used by the rest of the system.  If you
***************
*** 207,212 ****
  Please note that a package may be comprised of several tar files that are all
  unpacked in the same foo-directory.  Similarly there is no limit to the number
! of patches defined.  Splitting a patch into its important pieces is preferred
! to one giant patch.
  
  Once a package is added to the entities list you must then create a xml file
--- 221,230 ----
  Please note that a package may be comprised of several tar files that are all
  unpacked in the same foo-directory.  Similarly there is no limit to the number
! of patches defined.  Splitting a patch into individual bits, each of which
! describes one cleanly encapsulated change, is far better than one jumbo
! rollup patch.  The sample implementation aims to track upstream sources
! and among other things, this scheme makes it easier to see which patches
! have been taken up in new versions, and then remove just those from the
! build.  Overall, there are not expected to be many patches per package.
  
  Once a package is added to the entities list you must then create a xml file
***************
*** 257,260 ****
--- 275,287 ----
  it refers to one of phase3's components.
  
+ phase4 follows the same scheme as phase3, in that it uses phase2, and builds
+ completely independently.  phase4 does not do anything with a previously
+ built phase3.  &LFS-phase4-install; should be used with any directory
+ or file name to ensure it refers to the correct component; packages have
+ indpendent entries in the system file for each of the three subphases, as in
+ &phase4c-build-e2fsprogs; &phase4c-build-e2fsprogs; &phase4c-build-e2fsprogs;
+ 
+ 
+ =============================================================================
  So it built, now what:
  
***************
*** 285,327 ****
  implementation directly.  For you continue on to the next section.
  
  The test suite and the si:
  
  Those interesting in kicking the si's tires should grab the LSB's test suite
  and run it.  Bear in mind that the test suite requires software not in the
! spec so you need to install them before continuing.  Currently the items
! needed are pax and syslog.  The kernel will also be removed from the si soon
! and will have to be installed separately.  At present the rpm provided does not
! understand depends and requires the --nodeps option, this will be fixed.
! 
! The LSB test suite is composed of several smaller components and one larger
! package.  libchk and cmdchk are simple programs which verify that pieces
! required by the standard are installed.  Simply run them from within the
! chroot and observe their output.  Below is the result of running lsblibchk
! showing just two lines of interest the output of cmdchk is similar.
! 
! # /opt/lsblibchk/bin/lsblibchk
! Checking symbols in /lib/libc.so.6
! ...
! ...
! Unable to find library libGL.so.1
! ...
! ...
! 
! The large suite performs API tests as well as looking for missing files and
! directories.  Running the suite within a chroot is known to cause certain
! tests to fail, we are looking into alternatives at present.  Also the system's
! kernel not the chroot's is tested so it is important to use a compliant kernel
! -- this is currently 2.4.18 for ia32.
! 
! The suite will ask a few questions and then tell you to login as user 'vsx0'
! to start the tests.  Be prepared for the tests to take 3 hours, possibly
! longer.  There is also little status output during individual test runs so do
! not assume a test is hung because no output is occurring.  However if a test
! takes more than 2 hours you should investigate the cause as it may well be
! hung.  Once the tests are finished look in /home/tet/test_sets/results for a
! file containing details on the tests attempted as well as those actually run
! and their success or failure.  Along with each failure message there may be
! text explaining what exactly failed and why.  Some tests are optional yet may
! appear to be required so be sure to read the messages carefully.  The LSBsi
! only contains pieces listed as 'must' by the standard so some of the optional
! items are marked but these are not errors.
--- 312,376 ----
  implementation directly.  For you continue on to the next section.
  
+ =============================================================================
  The test suite and the si:
  
  Those interesting in kicking the si's tires should grab the LSB's test suite
  and run it.  Bear in mind that the test suite requires software not in the
! spec so you need to install them before continuing.  This is best accomplished
! by adding the Phase4a bundle, which if you built phase 4, will be named
! as lsbsi-test-{arch}-{version}.tar, for example lsbsi-test-ia64-1.3.tar.
! Unpack this into your lsbsi directory.  Copy the LSB test suite into the 
! lsbsi's /tmp directory and follow this recipe (adjust paths and other
! stuff as needed):
! 
! # sh /etc/init.d/syslog stop
! # cp /etc/fstab /usr/src/si/lsbsi/etc
! # chroot /usr/src/si/lsbsi
! bash-2.05b# mount /proc
! bash-2.05b# mount /dev/pts	(if needed)
! bash-2.05b# mount /dev/shm	(if needed)
! bash-2.05b# cd /tmp
! bash-2.05b# rpm -ivh lsb-runtime-test-1.3.3-1.i386.rpm
! bash-2.05b# passwd vsx0		(set some password you'll remember)
! bash-2.05b# syslogd -m 0
! bash-2.05b# in.telnetd -debu
! 
! At this point from another console virtual terminal or xterm, do
! 
! $ telnet localhost
! 
! log in as 'vsx0', and follow the prompts as they are displayed.
! For the lsbsi, you should answer no to the question of whether
! the implementatio provides a C shell, the other defaults are fine.
! 
! The test setup will ask for the root password, this is the 
! lsbsi's root password, not the host system's; it is set to
! 'lsbsi123'.
! 
! The test suite performs API tests as well as looking for missing files and
! directories.  It shouldn't have any failures that aren't documented in
! the release notes for that version of the sample implementation, although
! sometimes there are a couple of "login" related ones (on some systems
! these go away if you use a console vt instead of an xterm, and on others
! it seems to be the exact opposite).  The mount options for devpts may
! also affect a few tests, you can add a "mode=620" line to the fstab
! inside the chroot to take care of this.  Also note that the chroot is
! using the underlying system's kernel, so if the kernel does not comply
! the same failures will show through in the test.  2.4.19 and later
! kernels should have few if any issues; 2.4.18 depends on whether
! various patches have been applied or not, and earlier kernels are
! almost certain to have a few issues.
! 
! The full test suite takes over six hours; a few of the individual test cases
! are lengthy (in particular, T.pause takes 25 minutes or so; T.sigconcept
! takes 100 minutes, and T.sigsuspend takes 60).  There is little status output
! during individual test runs but do not assume a test is hung because no
! output is occurring.  However if a test takes more than 2 hours you should
! investigate the cause as it may well be hung.  Once the tests are finished
! look in /home/tet/test_sets/results for a file containing details on the
! tests attempted as well as those actually run and their success or failure.
! Along with each failure message there may be text explaining what exactly
! failed and why.  Some tests are optional yet may appear to be required so be
! sure to read the messages carefully.  The LSBsi only contains pieces listed
! as 'must' by the standard so some of the optional items are marked but these
! are not errors.