diff --git a/books/bookvol4.pamphlet b/books/bookvol4.pamphlet index ba28ffa..a9c639b 100644 --- a/books/bookvol4.pamphlet +++ b/books/bookvol4.pamphlet @@ -331,6 +331,17 @@ November 10, 2003 ((iHy)) \eject \pagenumbering{arabic} \setcounter{chapter}{0} % Chapter 1 +\begin{quote} +Confronting every new programmer learning a new language are +\begin{itemize} +\item The Cave of Artifacts +\item The Forest of Tooling +\item The Mountain of Language +\item The Cloud Castle of Mindset +\end{itemize} +-- Daniel Higginbotham in Clojure for the Brave and True +\end{quote} + \section{What is the purpose of the HACKPI domain?} HACKPI is a hack provided for the benefit of the axiom interpreter. @@ -2516,6 +2527,158 @@ that have slightly different semantics than their common lisp counterparts still exist in the system as macros due to this lisp. +\section{Changing GCL versions} + +Axiom lives on GNU Common Lisp. Axiom adds C code to the lisp image. +Axiom caches versions to ensure that nothing breaks. Changing GCL +versions has introduced subtle bugs at various times. The steps +necessary to introduce a new version are + +\begin{enumerate} +\item Add the latest GCL sources to Axiom +\item Update the patches to the new version +\item create diff -Naur patches to the gcl sources +\item update lsp/Makefile.pamphlet to apply the patch at build +\item add a new chunk to lsp/Makefile.pamphlet to build gcl-2.6.10 +\item Change the GCLVERSION to point at the new sources +\item change the Makefile to match Makefile.pamphlet +\end{enumerate} + +We assume in the following that \verb|$AXHOME| is the home directory and that +Axiom lives in the silver subdirectory. + +In more detail these steps are: + +\begin{enumerate} +\item Add the lateset GCL sources to Axiom +\begin{enumerate} +\item Download the latest GCL from gnu.org\\ + For these instructions assume the file is +\begin{verbatim} + gcl-Version_2_6_10.tar.gz +\end{verbatim} +\item move the tar file into /tmp\\ + We are going to make changes to the distribution via patches +\item untar the file +\begin{verbatim} + tar -zxf gcl-Version_2_6_10.tar.gz +\end{verbatim} +\item cd to the untarred directory +\begin{verbatim} + cd gcl-Version_2_6_10 +\end{verbatim} +\item rename the gcl directory\\ + Camm follows a convention that the top level directory in the + tar file is called gcl. Since we maintain several past versions + we need to rename this and re-tar it +\begin{verbatim} + mv gcl gcl-2.6.10 +\end{verbatim} +\item rename gcl to use our naming convention +\begin{verbatim} + tar -zcf gcl-2.6.10.tgz gcl-2.6.10 +\end{verbatim} +\item We move the original, renamed, retarred file to the zip directory +\begin{verbatim} + mv gcl-2.6.10.tgz $AXHOME/silver/zips +\end{verbatim} +\item We have to make sure to include the new file in the git commit +\begin{verbatim} + cd $AXHOME/silver +\end{verbatim} +\item Tell git we care about the file +\begin{verbatim} + git add zips/gcl-2.6.10.tgz +\end{verbatim} +\end{enumerate} +\item Update the patches to the new version +\begin{enumerate} +\item find the previous patches +\begin{verbatim} + ls $AXHOME/silver/zips/gcl-2.6.8pre7*patch +\end{verbatim} +\item for each patch do ( Step 3 ; Step 4 ) +\end{enumerate} +\item create diff -Naur patches to the gcl sources +\begin{enumerate} +\item assume we are looking at gcl-2.6.8pre7.h.linux.defs.patch\\ + The name tells us what file to patch. From the above we can see + that when Axiom builds GCL it will +\begin{verbatim} + cd lsp/gcl-2.6.8pre7 +\end{verbatim} + because GCL is built by the lsp/Makefile.pamphlet. That Makefile + will do a +\begin{verbatim} + cd h + patch gcl-2.6.10.h.linux.defs.patch +\end{verbatim} +\item move it to the zips directory +\begin{verbatim} + mv gcl-2.6.10.h.linux.defs.patch $AXHOME/silver/zips + cd $AXHOME/silver + git add zips/gcl-2.6.10.h.linux.defs.patch +\end{verbatim} +\end{enumerate} +\item update lsp/Makefile.pamphlet to apply the patch at build +\begin{enumerate} +\item edit lsp/Makefile.pamphlet +\item search for chunk \verb|gcl-2.6.8pre7.h.linux.defs.patch| +\item copy the chunk and name the new chunk +\verb|gcl-2.6.10.h.linux.defs.patch| +\end{enumerate} +\item add a new chunk to lsp/Makefile.pamphlet to build gcl-2.6.10 +\begin{enumerate} +\item find the subsection ``The GCL-2.6.8pre7 stanza'' +\item make a copy named ``The GCL-2.6.10 stanza'' +\item add the new patches +\item tell git we care +\begin{verbatim} + cd $AXHOME/silver + git add lsp/Makefile.pamphlet +\end{verbatim} +\end{enumerate} +\item Change the GCLVERSION to point at the new sources +\begin{enumerate} +\item emacs \verb|$AXHOME/silver/Makefile.pamphlet| +\item search for \verb|#GCLVERSION|, a Makefile comment line +\item the last line is uncommented. Assume it reads GCLVERSION=gcl-2.6.8pre7\\ + gcl-2.6.8pre7 was is the name of the current version we are + replacing. We will use this name in the next step +\item put a \# in front of the GCLVERSION variable to comment it out\\ + We maintain the list of old, working patches. We also remember the + names of the prior GCLVERSIONS in case we have to back up +\item Add a new line reading: +\begin{verbatim} + GCLVERSION=gcl-2.6.10 +\end{verbatim} + This will cause Axiom to untar this tgz file to get the sources + and apply the corresponding patches +\end{enumerate} +\item change the Makefile to match Makefile.pamphlet +\begin{itemize} +\item compile the tangle program +\begin{verbatim} + ( cd books ; gcc -o tangle tangle.c ) +\end{verbatim} +\item use books/tangle to extract the new Makefile +\begin{verbatim} + books/tangle Makefile.pamphlet >Makefile +\end{verbatim} +\end{itemize} +\end{enumerate} + \section{Literate Programming} The Axiom source code was originally developed at IBM Research. It was sold to The Numerical Algorithms Group (NAG) and was on diff --git a/changelog b/changelog index 90784b9..2e0f1b4 100644 --- a/changelog +++ b/changelog @@ -1,3 +1,5 @@ +20140710 tpd src/axiom-website/patches.html 20140710.02.tpd.patch +20140710 tpd books/bookvol4 add a section on changing GCL2 versions 20140710 tpd src/axiom-website/patches.html 20140710.01.tpd.patch 20140710 tpd Makefile remove leftover pdf files on clean 20140708 tpd src/axiom-website/patches.html 20140708.02.tpd.patch diff --git a/patch b/patch index 2f744f5..dcd3e72 100644 --- a/patch +++ b/patch @@ -1 +1,4 @@ -Makefile remove leftover pdf files on clean +books/bookvol4 add a section on changing GCL2 versions + +The process of moving GCL2 versions is reasonably simple. +It is documented in detail. diff --git a/src/axiom-website/patches.html b/src/axiom-website/patches.html index af1909a..ccfc19d 100644 --- a/src/axiom-website/patches.html +++ b/src/axiom-website/patches.html @@ -4538,6 +4538,8 @@ src/algebra/Makefile add LeftOreRing books/ps/v102leftorering.eps add missing image file 20140710.01.tpd.patch Makefile remove leftover pdf files on clean +20140710.02.tpd.patch +books/bookvol4 add a section on changing GCL2 versions