Re: [Axiom-developer] [build-improvements] Requests for discussion

[Cliff Yapp]

On Tuesday 01 August 2006 6:49 pm, Gabriel Dos Reis wrote:

> | Most open source installations ship a pre-generated ./configure
> | file and I think Axiom should be no different.
>
> Yes, that is what we will do.  That configure is generated by Autoconf
> based on configure.ac.  Autoconf does not expect pamphlet files.
> Autoconf want an input in a language it understands. Consequently, we
> must present configure.ac in a way appropriate for Autoconf.
> Therefore we cannot depend on noweb (notangle).

If I understand the question, you are asking how we can have only literate 
program files in Axiom at the get go and still not depend on noweb.  The 
simple answer is, we can't. 

> In my current system, the only dependency of configure on makefiles is
> when the makefiles are "touched" in a way that needs reconfiguration;
> and way to extract the documentation out of configure.ac.

I suppose I'm dense, but I thought it would end up like this:

1)  Have configure.ac and configure.ac.pamphlet both present in the top level 
directory.  configure.ac.pamphlet is where editing is done, and when a commit 
is made (for this one file) a configure.ac file is also committed (or even 
autogenerated by the server, if we want to go so far as to configure it to do 
so.)

2)  Extracting the documentation out of configure.ac.pamphlet would require 
the use of the notangle command, or once we have a lisp noweb using that 
tool. 

I've always wondered why LaTeX itself couldn't handle processing a pamphlet 
file as a regular latex file  - after all, couldn't it just replace 
<<chunckname>> [content] @ by a fancy version of \begin{verbatium}[content] 
\end{verbatium} or some such?  You would still need a notangle command to 
extract source code, but at least you could read the documentation without 
needing anything more than LaTeX.

I suppose I'm missing features noweb gives us though.

> | The first thing ./configure should do is check for noweb and tell
> | you what to do about it if it is not found.
>
> Yes, that is what is done in my current local tree.  That is one
> reason why we don' want configure.ac to depends on noweb.

That's why we will need to have both configure.ac and configure.ac.pamphlet.  
This will always be true if we want to avoid having the end user manually use 
some other tool to extract the first file, whether it is configure.ac or some 
other file.  As long as configure.ac.pamphlet is written and maintained in 
the .pamphlet file I don't see a problem with special casing the continual 
presence of configure.ac  - it's pretty much inevitable.

> | All this looks like a horrible hack to me - unless I am missing
> | something fairly basic. What is wrong with the usual way of using
> | noweb?
>
> See the explanations above.

I understand the desire to be able to bootstrap, but there is no way around 
it - we must have one non-pamphlet file present to kickstart the process.  
Personally I would suggest two or three - a set of Bash and Windows script 
files containing all the autoconf and other incantantations the user would 
need to make might simplify matters even more.

I don't think we should fear a couple of non-pamphlet files being present in 
the top level directory - indeed, it will simplify matters considerably from 
the user standpoint.  They won't know (and may not want to know) what a 
pamphlet file is all about - they just want to build and use the math program 
to do math.  In that case, the complete absence of anything familiar will 
turn them off.

I would suggest the minimal (and maybe maximal) set of:

README
configure.ac
buildaxiom.sh
buildaxiom_windows.<whatever windows uses>

README should be in basic, no frills ASCII text - about as universally 
readable as you can get.  It should explain a little about Axiom, and how to 
get started building it (tools needed, etc.)

> This is a hack; I agree.  No more horrible than what we currently do
> with noweb.  However, I don't like it.  That is why I called for
> discussion and suggestions for improvements :-)

There is no way to bootstrap without a "lower level" file present to kick the 
process off, unless (as you already attempted) the higher level files are 
also legal lower level files.  I don't think we want to redefine the literate 
strategy we use to that degree - it's not worth it.

In a way, it's the same problem Tim faced with Axiom being needed to build 
Axiom.  The only way out was (and still is) to have some files in lisp 
present, to teach lisp to read and understand BOOT and SPAD.  Same deal here.  
It's a universal problem - if we wanted to bootstrap a machine from a cold, 
memoryless, powerless state we would need some binary to feed it before it 
could start speaking assembly. True bootstrapping is a very rare event ;-).  
Normally even new platforms have their software cross compiled from other 
platforms, since the human beings involved don't want to make the translation 
themselves.  Anyway, that's another topic.

> To sum up.
>
> We need
>
>   (1) to write configure.ac directly in a language understood by Autoconf;
>   (2) a way to get the documentation out of configure.ac
>   (3) no dependency of configure.ac (and therefore configure) on noweb.

1 and 3 are solved by always having a current notangle of configure.ac present 
in the tree at all times.  As for two, I think we should assume a working 
notangle is available.  We have to assume SOMETHING is working, and since the 
generated document needs LaTeX to be processed I think the additional 
assumption of notangle (particularly if configure.ac can build it) is 
acceptable.

> For the long term, all Makefiles should be generated at configure time.

Agreed.

Cheers,
CY