[ << Build system notes ] | [Top][Contents][Index][ ? ] | [ Administrative policies >> ] | ||
[ < Building a bibliography ] | [ Up : Build system notes ] | [ Building an Ubuntu distro > ] |
12.5 Website build
Start here: ‘make/website.make’
The overall build system begins with How stepmake works.
Summary: when you type make website
this ends up running
‘GNUmakefile.in’ in the ‘git’ directory. Right at the
bottom, this has the lines:
# we want this separate for security; see CG 4.2. -gp website: $(MAKE) config_make=$(config_make) \ top-src-dir=$(top-src-dir) \ -f $(top-src-dir)/make/website.make \ website
On my system this expands to:
make --no-builtin-rules config_make=./config.make \ top-src-dir=/home/phil/lilypond-git \ -f /home/phil/lilypond-git/make/website.make \ website
We see that the $(MAKE)
expands to
make --no-builtin-rules
which is how MAKE
is
defined higher up the makefile. The -f switch defines the
makefile to be used - in this case
‘git/make/website.make’. That’s where all the action
happens.
We believe that note that *none* of the variables that are loaded (from depth to version numbers to whatever) are used in ‘website.make’. Instead, ‘website.make’ sets up its own variables at the top of the file. If you’re wondering if there’s some smart reason for this, then the answer is "no". It’s because I (GP) didn’t know/trust the original variables when I was writing that file.
Website build includes Building a bibliography.
Output from make -n website
Sorry, including this output directly produces problems in the build system. Please run:
make -n website &> my-file.txt
to see the full output from the make.
website.make variables
The file begins by setting up some variables. These may/might/probably mirror existing variables, but lacking any docs about those variables, I thought it would be simpler to keep everything in the same file.
Note that for security reasons, we don’t call scripts in the git dir when building on the web server. See Uploading and security. So we definitely want to keep those definitions for the WEBSITE_ONLY_BUILD.
After some split WEBSITE_ONLY_BUILD vs. normal build definitions, there’s another bunch of lines setting up generic variables.
website.make building parts
Parts of ‘website.make’:
-
website:
this is the "master" rule. It calls the other rules in order, then copies some extra files around - see below for further of the process it produces. -
website-version
: this calls the python scripts below:-
This writes a @version, @versionStable, and @versionDevel based on the top-level VERSIONS file, toscripts/build/create-version-itexi.py
out-website/version.itexi
-
This creates a ton of macros inscripts/build/create-weblinks-itexi.py
out-website/weblinks.itexi
. Stuff like @downloadStableLinuxNormal, @downloadStableWidows,@stableDocsNotationPdf{}
, @downloadDevelSourch-zh.It’s quite monstrous because it deals with combinations of stable/devel, source/docs, lang/lang/lang*10, etc.
-
-
website-xrefs:
creates files used for complicated "out-of-build" references toout-website/*.xref-map
If you just write @ref{}, then all’s groovy and we wouldn’t need this. But if you write @rlearning{}, then our custom texi2html init file needs to know about our custom xref file format, which tells our custom texi2html init file how to create the link.
GP: we should have a separate @node to discuss xrefs. Also, take a quick look at a generated xref file – it’s basically just a list of @node’s [sic teenager pluralization rule] from the file.
-
website-bib:
generates the bibliography texinfo files from the .bib files - in the case of the website build these are ‘others-did.bib’ and ‘we-wrote.bib’. -
website-texinfo:
this is the main part; it calles texi2html to generate the actual html. It also has a ton of options to texi2html to pass info to our custom init file.We have somewhere between 2-4 different ways "to pass info to our custom init file". This is highly Not Good (tm), but that’s how things work at the moment.
After texi2html, it does some black magick to deal with untranslated nodes in the translations. Despite writing that part, I can’t remember how it works. But in theory, you could figure it out by copy&pasting each part of the command (by "part", I mean "stuff before each | pipe"), substituting the variables, then looking at the text that’s output. For example,
ls $(OUT)/$$l/*.html
is going to print a list of all html files, in all languages, in the build directory. Then more stuff happens to each of those files (that’s what xargs does).
-
website-css:
just copies files to the build dir. -
website-pictures, website-examples:
more file copies, with an if statement to handle if you don’t have any generated pictures/examples. -
web-post:
runs:scripts/build/website_post.py
which, it adds the "this page is translated in klingon" to the bottom of html pages, and adds the google analytics javascript. It also has hard-coded lilypond version numbers, which is Bad (tm).
Here’s a summary of what gets called, in what order, when we run
make website
website: website-texinfo: website-version: creates version.itexi and weblinks.itexi website-xrefs: runs extract_texi_filenames.py website-bibs: creates bibliography files, described above website-css: copies css files website-pictures: copies pictures website-examples: copies examples web-post: runs website_post.py Then some file copying
[ << Build system notes ] | [Top][Contents][Index][ ? ] | [ Administrative policies >> ] | ||
[ < Building a bibliography ] | [ Up : Build system notes ] | [ Building an Ubuntu distro > ] |