loncom/build/readme.html - view

File: [LON-CAPA] / loncom / build / readme.html
Revision 1.11: download - view: text, annotated - select for diffs
Wed Jan 17 12:49:33 2001 UTC (23 years, 4 months ago) by harris41
Branches: MAIN
CVS tags: HEAD

entered in documentation about the format of loncapafiles.html and
its interaction with parse.pl (regarding software packaging make
targets).  I also discuss nature of different makefile approaches
and according to what experience/rationale the current solution
is implemented. -Scott

1: <HTML> 2: <HEAD> 3: <META NAME="GENERATOR" CONTENT="Scott Harrison and Emacs Version 3.14159265358979"> 4: <TITLE>LON-CAPA Software Developer Instructions</TITLE> 5: </HEAD> 6: <BODY> 7: <H1>LON-CAPA Software Developer Instructions</H1> 8: 9: <OL> 10: <LI><A HREF="#Using_CVS">Using CVS</A> 11: <UL> 12: <LI><A HREF="#cvslog">Logging in and out (cvs login; cvs logout)</A> 13: <LI><A HREF="#cvsget">Getting files (cvs update -d)</A> 14: <LI><A HREF="#cvsupdate">Updating files (cvs update -d)</A> 15: <LI><A HREF="#cvssave">Saving files (cvs commit)</A> 16: <LI><A HREF="#cvsadd">Adding files (cvs add)</A> 17: <LI><A HREF="#cvsadddir">Adding directories (cvs add/import)</A> 18: <LI><A HREF="#cvsnotsure">What to do when you're not sure about your files (cvs update)</A> 19: </UL> 20: <LI><A HREF="#makeHTML">Viewing the software (make HTML)</A> 21: <LI><A HREF="#makebuild">Compiling the software (make build)</A> 22: <LI><A HREF="#loncapafiles">Adding/removing files from the LON-CAPA installation (doc/loncapafiles/loncapafiles.html)</A> 23: <LI><A HREF="#configversusnonconfig">Configurable files versus non-configurable files</A> 24: <LI><A HREF="#makeinstall">Updating the non-configurable files on your machine (make install)</A> 25: <LI><A HREF="#makeconfiginstall">Updating the configurable files on your machine (make configinstall)</A> 26: <LI><A HREF="#makeRPM">Building RPMs (make RPM)</A> 27: </OL> 28: 29: <OL> 30: <A NAME="Using_CVS"> 31: <LI><H2>Using CVS</H2> 32: <UL> 33: <LI><A NAME="cvslog"> 34: <H3>Using CVS: Logging in and out (cvs login; cvs logout)</H3> 35: <LI><A NAME="cvsget"> 36: <H3>Using CVS: Getting files (cvs update -d)</H3> 37: <LI><A NAME="cvsupdate"> 38: <H3>Using CVS: Updating files (cvs update -d)</H3> 39: <LI><A NAME="cvssave"> 40: <H3>Using CVS: Saving files (cvs commit)</H3> 41: <LI><A NAME="cvsadd"> 42: <H3>Using CVS: Adding files (cvs add)</H3> 43: <LI><A NAME="cvsadddir"> 44: <H3>Using CVS: Adding directories (cvs add/import)</H3> 45: <LI><A NAME="cvsnotsure"> 46: <H3>Using CVS: What to do when you're not sure about your files (cvs update)</H3> 47: </UL> 48: <LI><A NAME="makeHTML"> 49: <H2>Viewing the software (make HTML)</H2> 50: <STRONG>Commands</STRONG> 51: <FONT COLOR="#008800"> 52: <PRE> 53: cd loncom/build 54: rm -Rf HTML <I>(or alternatively, "make clean")</I> 55: make HTML 56: cd HTML 57: <I>(look at the index.html file with a web browser such as Netscape)</I> 58: </PRE> 59: </FONT> 60: <STRONG>General description of what happens</STRONG> 61: <P> 62: This is the actual make target code. 63: <FONT COLOR="#880000"> 64: <PRE> 65:  66: HTML: 67: install -d HTML 68: cp ../../doc/loncapafiles/*.gif HTML 69: perl parse.pl ../../doc/loncapafiles/loncapafiles.html HTML > HTML/index.html 70:  71: </PRE> 72: </FONT> 73: What basically happens is that specially marked-up data in the LON-CAPA 74: cvs repository file <TT>doc/loncapafiles.html</TT> is parsed into a more 75: viewable format by <TT>loncom/build/parse.pl</TT>. The resulting 76: file gives a very well organized view of all the files, directories, 77: links, ownerships, permissions, and brief documentation of what each 78: file does. 79: </P> 80: <LI><A NAME="makebuild"> 81: <H2>Compiling the software (make build)</H2> 82: <STRONG>Commands</STRONG> 83: <FONT COLOR="#008800"> 84: <PRE> 85: cd loncom/build 86: make build 87: </PRE> 88: </FONT> 89: <STRONG>General description of what happens</STRONG> 90: <P> 91: This is the actual make target code. 92: <FONT COLOR="#880000"> 93: <PRE> 94:  95: build: 96: perl parse.pl ../../doc/loncapafiles/loncapafiles.html build > Makefile.build 97: make -f Makefile.build all 98:  99: </PRE> 100: </FONT> 101: <TT>loncom/build/parse.pl</TT> reads in all the build information out 102: of <TT>doc/loncapafiles/loncapafiles.html</TT>. A new Makefile named 103: <TT>loncom/build/Makefile.build</TT> is dynamically constructed. 104: This dynamically generated Makefile is then run to build/compile 105: all the software targets from source. This currently takes 10 minutes 106: (depends on the speed of the machine you compile with). 107: </P> 108: <STRONG>Example</STRONG> 109: <P> 110: Here is information for one file <TT>tth.so</TT> provided in 111: <TT>doc/loncapafiles/loncapafiles.html</TT>. 112: <FONT COLOR="#330066"> 113: <PRE> 114: <BR><METAGROUP> 115: <BR><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"> 116: <BR><DESCRIPTION> 117: <BR>shared library file for dynamic loading and unloading of TeX-to-HTML functionality 118: <BR></DESCRIPTION> 119: <BR><BUILD> 120: <BR>loncom/modules/TexConvert/tthperl/commands 121: <BR></BUILD> 122: <BR><DEPENDENCIES> 123: <BR>../tthdynamic/tthfunc.c 124: <BR>../ttmdynamic/ttmfunc.c 125: <BR></DEPENDENCIES> 126: </PRE> 127: </FONT> 128: <TT>loncom/build/parse.pl</TT> sees the <B>BUILD</B> tags and sets up 129: a dynamic file <TT>Makefile.build</TT> to run the command inside the 130: <B>BUILD</B> tags (currently, <B>DEPENDENCIES</B> is not used for anything 131: besides documentation). 132: </P> 133: <P> 134: Here is an example of a dynamically generated <TT>Makefile.build</TT> 135: that builds two LON-CAPA files (one of which is <TT>tth.so</TT>). 136: <FONT COLOR="#330066"> 137: <PRE> 138: all: ../homework/caparesponse/capa.so ../modules/TexConvert/tthperl/tth.so 139: 140: ../homework/caparesponse/capa.so: ../homework/caparesponse/caparesponse.c ../ho 141: mework/caparesponse/caparesponse.pm alwaysrun 142: cd ../homework/caparesponse/; sh ./commands 143: 144: ../modules/TexConvert/tthperl/tth.so: ../modules/TexConvert/tthperl/../tthdynam 145: ic/tthfunc.c ../modules/TexConvert/tthperl/../ttmdynamic/ttmfunc.c 146: cd ../modules/TexConvert/tthperl/; sh ./commands 147: 148: alwaysrun: 149: </PRE> 150: </FONT> 151: </P> 152: <LI><A NAME="loncapafiles"> 153: <H2>Adding/removing files from the LON-CAPA installation (doc/loncapafiles/loncapafiles.html)</H2> 154: <STRONG>To add and remove (and alter)</STRONG> 155: All that you have to do to alter the behavior of the installation is 156: edit a single file (<TT>doc/loncapafiles/loncapafiles.html</TT>). 157: Adding, removing, and altering files requires proper attention 158: to the syntax of file format of course. 159: <STRONG>File Format</STRONG> 160: <P> 161: The preceding <A HREF=#"makebuild">"make build"</A> documentation 162: gives an example <B>METAGROUP</B> entry describing one particular file. 163: All data within <TT>loncapafiles.html</TT> is specified according 164: to markup tags. The format and syntax of <TT>loncapafiles.html</TT> 165: is currently best described by the HTML documentation code at the beginning of 166: loncapafiles.html (as well as, by example, seeing how various 167: information is coded). All in all, the syntax is quite simple. 168: </P> 169: <STRONG>Philosophy and notes (the thing nobody reads)</STRONG> 170: <P> 171: Packaging the software from CVS onto a machine file system requires many 172: things: 173: <UL> 174: <LI>documenting every component of the software, 175: <LI>handling CVS <U>source</U> to file system <U>target</U> information 176: <LI>handling (according to a hierarchical scheme of grouping) file 177: ownership and permissions, 178: <LI>handling (according to a hierarchical scheme of grouping) directory 179: ownership and permissions, 180: <LI>handling symbolic links 181: <LI>providing for multiple options of installation targets 182: (RedHat versus Debian for instance), 183: <LI>providing for different file ownerships and permissions to apply 184: to the same file, 185: <LI>allowing system software documentation to be automatically generated 186: (see information on <A HREF="#makeHTML">"make html"</A>), 187: <LI>providing information in an easily adjustable form as new demands 188: are made on the software packaging system, 189: <LI>providing software package information (for RPM), 190: <LI>having information in a format that allows for troubleshooting 191: the current status of the machine file system, 192: <LI>allow for changes to the structure of the CVS repository, 193: <LI>and something that is simple enough for any one to immediately work with, 194: without having to learn specifics (or hidden traps) of complicated Makefile's 195: or a new macro language (m4?). 196: </UL> 197: </P> 198: <P> 199: I looked into, and tried, different ways of accomplishing the above 200: including automake and recursive make. The automake system seemed quite 201: complicated (and needlessly so in terms of this project since, by and large, 202: it works to coordinate many different types of build/compilation parameters 203: whereas we are more concerned with installation parameters). Recursive make 204: has significant deficiencies in the sense that not all the information 205: is kept in one place, and there are significant levels of dependency 206: between all the things that must be done to keep software packaging 207: up to date. A particularly convincing article I found when looking into 208: much of this was 209: <A HREF="http://www.pcug.org.au/~millerp/rmch/recu-make-cons-harm.html"> 210: "Recursive Make Considered Harmful" by Peter Miller</A>. Complicating 211: matters was, at the time, it was unclear as to what categories 212: of software files we had, and whether or not the directory structure 213: of CVS would remain constant. With an ever-developing directory structure 214: to CVS, I preferred to organize the information on a per-file basis 215: as opposed to a per-directory basis (although there is a successful 216: implementation of a standard big Makefile in <TT>loncom/Makefile</TT>). 217: Additionally, a standard big Makefile assumes certain "normalcy" to 218: the directory structure of different potential operating system directories 219: (RedHat vs. Debian). 220: </P> 221: <P> 222: If you take time to look at loncapafiles.html 223: (and perhaps run the <A HREF="#makeHTML">make HTML</A> command) 224: you will find that the organizing information according to the markup 225: syntax in <TT>loncapafiles.html</TT> is simple. Simple is good. 226: </P> 227: <P> 228: <TT>loncom/build/parse.pl</TT> is the script (invoked automatically 229: by the various targets in <TT>loncom/build/Makefile</TT>) that reads 230: <TT>doc/loncapafiles/loncapafiles.html</TT>. <TT>parse.pl</TT> 231: is capable of reading and returning different types of information 232: from <TT>loncapafiles.html</TT> depending on how <TT>parse.pl</TT> 233: is invoked. <TT>parse.pl</TT> has yet to have introduced new sources 234: of error, and has been tested in quite a number of ways. As with 235: any parser however, I remain paranoid. 236: </P> 237: <P> 238: My regrets with the current system is that <TT>parse.pl</TT> is 239: slow (can take 1 minute to run) and includes a few tidbits of code, 240: specific to the make process, that probably should be in 241: <TT>loncom/build/Makefile</TT>. Additionally, <TT>loncapafiles.html</TT> 242: should have a DTD and all those other good SGML-ish things (and parsing 243: should be done with a real SGML-derived parser). 244: </P> 245: <P> 246: On the plus side, the <TT>parse.pl</TT>-<TT>loncapafiles.html</TT> 247: combination has been working very efficiently and error-free. 248: </P> 249: <LI><A NAME="configversusnonconfig"> 250: <H2>Configurable files versus non-configurable files</H2> 251: <LI><A NAME="makeinstall"> 252: <H2>Updating the non-configurable files on your machine (make install)</H2> 253: <LI><A NAME="makeconfiginstall"> 254: <H2>Updating the configurable files on your machine (make configinstall)</H2> 255: <LI><A NAME="makeRPM"> 256: <H2>Building RPMs (make RPM)</H2> 257: </OL> 258: </BODY> 259: </HTML>