--- loncom/build/readme.html 2001/01/17 11:57:59 1.8 +++ loncom/build/readme.html 2001/01/17 13:50:47 1.16 @@ -1,5 +1,12 @@ + +
+ +cd loncom/build -rm -Rf HTML (or alternatively, "make clean") -make HTML -cd HTML -(look at the index.html file with a web browser such as Netscape) +make buildGeneral description of what happens @@ -88,15 +92,15 @@ cd HTML This is the actual make target code.
- + build: perl parse.pl ../../doc/loncapafiles/loncapafiles.html build > Makefile.build make -f Makefile.build all - +loncom/build/parse.pl reads in all the build information out -of doc/loncapafiles/loncapafiles.html. A new Makefile named +of doc/loncapafiles/loncapafiles.html. A new Makefile named loncom/build/Makefile.build is dynamically constructed. This dynamically generated Makefile is then run to build/compile all the software targets from source. This currently takes 10 minutes @@ -106,7 +110,7 @@ all the software targets from source. T
Here is information for one file tth.so provided in
doc/loncapafiles/loncapafiles.html.
-
+
<METAGROUP>
<LONCAPA TYPE=LOCATION DIST="redhat6.2" SOURCE="loncom/modules/TexConvert/tthperl/tth.so" TARGET="usr/lib/perl5/site_perl/5.005/tth.so" CATEGORY="system file">
@@ -129,8 +133,8 @@ besides documentation).
Here is an example of a dynamically generated Makefile.build
-that builds two LON-CAPA files (one of which is tth.so.
-
+that builds two LON-CAPA files (one of which is tth.so).
+
all: ../homework/caparesponse/capa.so ../modules/TexConvert/tthperl/tth.so
@@ -148,12 +152,276 @@ alwaysrun:
+All that you have to do to alter the behavior of the installation is +edit a single file (doc/loncapafiles/loncapafiles.html). +Adding, removing, and altering files requires proper attention +to the syntax of file format of course. +
+File Format ++The preceding "make build" documentation +gives an example METAGROUP entry describing one particular file. +All data within loncapafiles.html is specified according +to markup tags. The format and syntax of loncapafiles.html +is currently best described by the HTML documentation code at the beginning of +loncapafiles.html (as well as, by example, seeing how various +information is coded). All in all, the syntax is quite simple. +
+Philosophy and notes (the thing nobody reads) ++Packaging the software from CVS onto a machine file system requires many +things: +
+I looked into, and tried, different ways of accomplishing the above +including automake and recursive make. The automake system seemed quite +complicated (and needlessly so in terms of this project since, by and large, +it works to coordinate many different types of build/compilation parameters +whereas we are more concerned with installation parameters). Recursive make +has significant deficiencies in the sense that not all the information +is kept in one place, and there are significant levels of dependency +between all the things that must be done to keep software packaging +up to date. A particularly convincing article I found when looking into +much of this was + +"Recursive Make Considered Harmful" by Peter Miller. Complicating +matters was, at the time, it was unclear as to what categories +of software files we had, and whether or not the directory structure +of CVS would remain constant. With an ever-developing directory structure +to CVS, I preferred to organize the information on a per-file basis +as opposed to a per-directory basis (although there is a successful +implementation of a standard big Makefile in loncom/Makefile). +Additionally, a standard big Makefile assumes certain "normalcy" to +the directory structure of different potential operating system directories +(RedHat vs. Debian). +
++If you take time to look at loncapafiles.html +(and perhaps run the make HTML command) +you will find that the organizing information according to the markup +syntax in loncapafiles.html is simple. Simple is good. +
++loncom/build/parse.pl is the script (invoked automatically +by the various targets in loncom/build/Makefile) that reads +doc/loncapafiles/loncapafiles.html. parse.pl +is capable of reading and returning different types of information +from loncapafiles.html depending on how parse.pl +is invoked. parse.pl has yet to have introduced new sources +of error, and has been tested in quite a number of ways. As with +any parser however, I remain paranoid. +
++My regrets with the current system is that parse.pl is +slow (can take 1 minute to run) and includes a few tidbits of code, +specific to the make process, that probably should be in +loncom/build/Makefile. Additionally, loncapafiles.html +should have a DTD and all those other good SGML-ish things (and parsing +should be done with a real SGML-derived parser). +
++On the plus side, the parse.pl-loncapafiles.html +combination has been working very efficiently and error-free. +
+The current list of configurable files for the LON-CAPA system is +/etc/httpd/access.conf, /etc/smb.conf, /etc/ntp.conf, /etc/krb.conf, +/etc/atalk/config, /etc/ntp/step-tickers, +/home/httpd/html/res/adm/includes/copyright.tab, +/home/httpd/html/res/adm/includes/un_keyword.tab, +/home/httpd/hosts.tab, and +/home/httpd/spare.tab. +
++All of these configurable files contain machine-specific information. +For instance, the LON-CAPA system relies on unique host IDs such +as msua3, s1, s2, msul1, and 103a1 (specified as a "PerlSetVar lonHostID" +field within /etc/httpd/access.conf). +Non-configurable files simply do NOT have machine-specific information. +The impact on updating software +
+What this means in terms of software updating is that +
+cd loncom/build +make install ++ +General description of what happens +
+This is the actual make target code.
+
+
+
+install: build
+ perl parse.pl ../../doc/loncapafiles/loncapafiles.html install > Makefil
+e.install
+ make -f Makefile.install SOURCE="../.." TARGET="" directories
+ make -f Makefile.install SOURCE="../.." TARGET="" files
+ make -f Makefile.install SOURCE="../.." TARGET="" links
+
+
+
+For safety reasons (so as to not mess up a machine's configuration),
+configuration files are NOT installed during this step. This means
+that files such as /etc/httpd/access.conf, /etc/smb.conf, /etc/atalk/config,
+/home/httpd/html/res/adm/includes/copyright.tab, and
+/home/httpd/spare.tab are not overwritten, but remain as old, non-updated
+copies. (To automatically update these files and save/restore
+their encoded machine configuration, you must run "make configinstall").
+
+cd loncom/build +make configinstall ++ +General description of what happens +
+This is the actual make target code.
+
+
+
+configinstall:
+ # there is a dependency on having directories in place, but oh well...
+ perl parse.pl ../../doc/loncapafiles/loncapafiles.html configinstall > Makefile.configinstall
+ make -f Makefile.configinstall SOURCE="../.." TARGET="" configfiles
+ perl loncaparestoreconfigurations lasttimestamp
+ make -f Makefile.configinstall TARGET="" configpermissions
+
+
+
+Configuration files are installed during this step. This means
+that files such as /etc/httpd/access.conf, /etc/smb.conf, /etc/atalk/config,
+/home/httpd/html/res/adm/includes/copyright.tab, and
+/home/httpd/spare.tab are overwritten. Before being overwritten,
+a backup copy is made though. Information is read out of these
+backup copies and restored to the new files by the
+loncaparestoreconfigurations script. To ensure that
+new file permissions and ownerships are installed, a final set of
+chown and chmod commands are called for each of
+the configuration files.
+
+If you are truly paranoid, you can just make the +Makefile.configinstall file and then save, copy, +and restore all the configuration values yourself. +loncaparestoreconfigurations is pretty smart though, has yet to +fail, and besides, a backup copy is always made (time-stamped so that backup +copies are not overwritten). +
+cd loncom/build +rm -Rf BinaryRoot (or alternatively, "make clean") +make RPM + (to subsequently install, you can type commands like + "rpm -Uvh --force LON-CAPA-base-3.1-1.i386.rpm") ++ + +WARNING!!!!!!!!!!!!!! +
+Never never never never never manually install the +LON-CAPA-setup-3.1-1.i386.rpm. This RPM is meant to only be +installed by the CD installation process (it wipes out +the existing /etc/passwd file). +
+Configuration files ++Configuration files are automatically saved with the file suffix +".rpmsave". So /etc/httpd/conf/access.conf is saved as +/etc/httpd/conf/access.conf.rpmsave. You can restore +the machine-specific configuration information by running +the /usr/sbin/loncaparestoreconfigurations. However, +a warning is important here. If you install an RPM twice +without restoring your configuration, you will overwrite the +".rpmsave" files. +
+General description of what happens +
+This is the actual make target code.
+
+
+
+RPM: BinaryRoot
+ cat base_file_list.txt | perl make_rpm.pl base 3.1 '' '' BinaryRoot
+ cat setup_file_list.txt | perl make_rpm.pl setup 3.1 '' '' BinaryRoot
+
+BinaryRoot:
+ perl parse.pl ../../doc/loncapafiles/loncapafiles.html BinaryRoot
+
+
+
+A BinaryRoot directory is generated that reflects the locations,
+ownerships, permissions, and contents for all the CVS source
+files, compiled binaries, directories, and links as they should eventually
+occur on the '/' filesystem location.
+
+loncom/build/make_rpm.pl is robust (tested over the +span of months) and, unlike other automated RPM-builders, cleanly +builds new RPMs without any after-effect of temporary files left +on the system. (On the negative side, there are a number of +LON-CAPA specific customizations inside make_rpm.pl which, for +the sake of reusability, should eventually be removed). Two new RPMs +are generated: LON-CAPA-base-3.1-1.i386 and LON-CAPA-setup-3.1-1.i386.rpm +(again, never manually install LON-CAPA-setup-3.1-1.i386.rpm). +
The server encountered an internal error or misconfiguration and was unable to complete your request.
Please contact the server administrator at root@localhost to inform them of the time this error occurred, and the actions you performed just before this error.
More information about this error may be available in the server error log.