LilyPond Contributor's Guide: 12.5 Website build

## 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:

  - >     scripts/build/create-version-itexi.py

    This writes a @version, @versionStable, and @versionDevel based on the top-level VERSIONS file, to `out-website/version.itexi`

  - >     scripts/build/create-weblinks-itexi.py

    This creates a ton of macros in `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 to `out-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

#### LilyPond — Contributor’s Guide