org-build-system: use CAPTION instead of NAME
[worg.git] / dev / org-build-system.org
1 #+TITLE:    Org-mode Build System
2 #+AUTHOR:   Achim Gratz
3 #+EMAIL:    Stromeko <at> NexGo.DE
4 #+STARTUP:    align fold nodlcheck hidestars oddeven intestate
5 #+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
6 #+TAGS:       Write(w) Update(u) Fix(f) Check(c)
7 #+LANGUAGE:   en
8 #+PRIORITIES: A C B
9 #+CATEGORY:   worg
10 #+OPTIONS:    H:3 num:nil toc:t \n:nil @:t ::t |:t ^:t -:t f:t *:t TeX:t LaTeX:t skip:nil d:(HIDE) tags:not-in-toc
11
12 * Introduction
13
14 Org can be run directly from sources, however usually it is
15 byte-compiled and installed before use.  Also, the documentation needs
16 to be rebuilt from their respective sources, registered and put into a
17 place where it can be found.  Instead of you having to do all this by
18 hand, a build system based on GNU make will do it for you.  The Org
19 build system makes extensive use of GNU make features and requires at
20 least version 3.81 (use of the latest released version is
21 recommended).
22
23 * Build System Structure
24
25 The build system consists of these files:
26
27 : <org-mode>/Makefile
28 : <org-mode>/local.mk
29 : <org-mode>/doc/Makefile
30 : <org-mode>/etc/Makefile
31 : <org-mode>/lisp/Makefile
32 : <org-mode>/mk/default.mk
33 : <org-mode>/mk/targets.mk
34 : <org-mode>/mk/org-fixup.el
35
36 Additional files are present for the Orgmode server in the
37 =<org-mode>/mk/= subdirectory.  An additional file
38 =<org-mode>/mk/version.mk= is present in the distribution archives to
39 record the version information that gets used when building from these
40 sources.
41
42 ** Top Level =Makefile=
43
44 This file provides only the help.  Short help can be requested by
45 =make help=, while =make helpall= will list all documented targets.
46 Undocumented targets may exist for internal purposes and can be
47 changed or removed at any time.
48
49 All other functionality of the build system is provided in separate
50 files, which will either be explicitly included from the top level or
51 implicitly read by GNU make.
52
53 ** Local Customization =local.mk=
54
55 *Never push* =local.mk= *to any public branch!*
56
57 The build system is an integral part of Org.  To allow easy local
58 customization, that customization must never become part of the
59 official Git repository.  On the other hand the build system must work
60 even when no local customization has been applied.  Therefore when the
61 file =local.mk= does not exist, a local customization template will be
62 created that copies some settings that most commonly would need to be
63 changed from =mk/default.mk=.  The template includes some comments
64 that are hopefully self-documenting.  As long as all necessary
65 programs are available, the customization should in most cases be
66 limited to setting =prefix= correctly.
67
68 If you need to do more extensive changes, copy the relevant parts from
69 =mk/default.mk= to =local.mk= (or maybe even the whole file if that
70 seems easier to you, but you'll have to remember to check =local.mk=
71 whenever =default.mk= changes in the repository).  Please look at some
72 of the [[Customization][Customization Examples]] to get an idea of what is possible.
73
74 ** Second Level =Makefile=
75
76 The =Makefile= in subdirectories can be invoked from the top level only
77 since they rely on the definitions that have been made there.
78
79 ** Defaults =mk/default.mk=
80
81 *Never change anything in* =mk/default.mk= *— always do your changes in*
82  =local.mk= *!*
83
84 The defaults are designed to work on a typical GNU/Linux system.  For
85 system-wide installation as assumed by the build system the user must
86 be able to obtain administrative privileges via sudo.  If sudo is not
87 available, the user running make must have the necessary privileges to
88 do the install (i.e. full access to the build and install
89 directories).  Besides Emacs, the following programs must be available
90 in PATH:
91
92 - find
93 - install
94 - rm
95
96 The following programs are optional when loss of functionality can be
97 tolerated:
98
99 - install-info
100 - makeinfo
101 - texi2pdf
102 - sudo
103 - git
104
105 ** Make Targets =mk/targets.mk=
106
107 All targets that the Org build system can build are defined here.
108 Most of the actual work will be handed off to the second level
109 =Makefile= in their respective subdirectories.  It is possible to
110 override some parts of the build system by defining some variables.
111 This is largely untested and consequently unsupported, but may still
112 be useful in some situations.  The following variables are considered
113 stable:
114
115 - =TEST_NO_AUTOCLEAN= :: Define to a non-null value to keep the test
116      directory around for inspection.  This is mostly useful for
117      debugging the test suite.
118 - =ORGVERSION= :: Can be used to override the automatic determination
119                   of the version strings.  If you find a need to do
120                   this, it is likely a bug someplace else.  *Never
121                   define this in a customization file!*
122 - =GITVERSION= :: See =ORGVERSION=.  Please do not define it to a
123                   value that could be confused with a real Git
124                   version string.
125 - =GITSTATUS= :: See =GITVERSION=.  If this variable is defined
126                  non-null, the string ".dirty" will be appended to the
127                  Git version string, which indicates a locally
128                  modified version.
129
130 ** Utilities =mk/org-fixup.el=
131
132 This is a collection of some Emacs Lisp routines that implement basic
133 functionality of the build system.  This mainly eliminates the need
134 for some external programs and thus reduces the number of external
135 dependencies.
136
137 A few of these functions have been designed to be used from the
138 command line or even from within Emacs itself.  This is an aid for
139 manually building a working Org installation when the external
140 dependencies of the build system cannot be met.  See
141 [[Support%20for%20Manual%20Build][Support for Manual Build]].
142
143 * Make Targets
144
145 Each time you want GNU make to build something for you, you need to
146 tell it what that is: this is called a /target/ or /goal/.  For each
147 /target/, make determines the /prerequisites/ and then goes on to
148 build them in the order of dependence.  A /target/ can be an actual
149 file that GNU make should build, but more commonly it is just a
150 moniker (called a /phony target/) that has the files to build as
151 /prerequisites/.
152
153 ** Help
154
155 - =help= :: Shows a brief list of the most commonly used /targets/
156             with a short description of what they do.
157 - =targets= :: This is an alias for =help=, mandated by GNU Makefile
158                conventions.
159 - =helpall= :: Shows (almost) all /targets/ and a short description of
160                what they do.
161
162 ** Configuration Check
163
164 - =config-test= :: Show the test customization.
165 - =config-cmd= :: Show what commands will be used.
166 - =config-all= :: Show all customization.
167
168 ** Build
169
170 - =all= :: Build all of Org: byte-compile the source files and create
171            all documentation.[fn:1]
172 - =compile= :: Ensure a clean source directory and then byte-compile
173                the source files using the [[Compilation Methods][compilation method]] =dirall=
174                by default.
175 - =compile-dirty= :: Byte-compile just those sources that haven't been
176      compiled already or are newer than their byte-compiled
177      counterpart.[fn:2]
178 - =single= :: The same as =compile=, but uses the [[Compilation Methods][compilation method]]
179               =single= (unless overridden by defining =ORGCM= on the
180               command line).
181 - =autoloads= :: Create just the autoload files, but do not
182                  byte-compile anything.
183
184 ** Test
185
186 - =test= :: runs =compile= and then the full testsuite.[fn:3]
187 - =check= :: An alias for =test=, to be compatible with GNU style.
188 - =test-dirty= :: Run the full testsuite on whatever currently is
189                   available, compiled or not.
190
191 ** Installation
192
193 - =install= :: Build all of Org and install it.
194 - =install-etc= :: Install only the =etc/= part of Org.
195 - =install-lisp= :: Install only the =lisp/= part of Org.
196 - =install-info= :: Build the documentation and install only the info
197                     documentation.
198
199 ** Documentation
200
201 - =doc= :: Create all documentation.[fn:1]
202 - =docs= :: An alias for =doc=.
203 - =info= :: Create only GNU Info documentation (requires GNU Makeinfo).
204 - =pdf= :: Create only PDF documentation (requires PDFTeX).
205 - =card= :: Create only the reference card (requires PDFTeX).
206 - =refcard= :: An alias for =card=.
207
208 ** Cleaning
209
210 - =clean= :: Cleans in =lisp/= and =doc/=.
211 - =cleanall= :: Cleans everything that can be cleaned, including
212                 several types of backup files, so do not use this when
213                 you have active edit sessions!
214 - =clean-install= :: Removes a previous Org installation.[fn:4]
215 - =cleantest= :: Removes a test directory if it exists.[fn:5]
216
217 ** Compatibility and Convenience
218
219 - =up0= :: Updates the current Git branch from upstream by doing a
220            =git pull=.
221 - =up1= :: Does =up0= and then builds and checks Org.
222 - =up2= :: Does =up1= and installs Org if there was no test error.
223 - =update= :: Does =up0= and then builds Org.  Does not test.
224 - =update2= :: Does =update= and then installs.  This is not
225                recommended, since there is no way of telling whether
226                the just built Org has errors.
227 - =uncompiled= :: Removes any byte-compiled files and then creates the
228                   autoload files.  You can then use the Git worktree
229                   almost like an installed version of Org.  Not
230                   recommended for normal use of Org.
231 - =local.mk= :: Create a customization template.  If one already
232                 exists, you need to rename or remove it first.
233
234 * Customization
235
236 Changing the behaviour of the build system to conform to your local
237 system rules is done by editing the file =local.mk=.  The standard
238 template that is created when this file does not exist offers only the
239 most common customization variables, but you are free to customize
240 anything that =mk/default.mk= offers (but you really have to know what
241 you are doing for some of this).  Remember to only change =local.mk=,
242 please.
243
244 ** Simple Customization
245 *** Default target
246
247 The /default target/ is what =make= tries to build when you don't give
248 it anything else to do.  For compatibility with the old build system,
249 a freshly created =local.mk= will have =oldorg= defined as the default
250 target.  If you remove that line entirely from =local.mk=, =all= will
251 become the default target.  But you can put any other target there
252 that you want to become the default target or even define a new one
253 (OK, that isn't simple customization anymore).
254
255 *** Including sources from =contrib/=
256
257 If you just want to try out some of the things in =contrib/=, you can
258 simply add the directory to =load-path=.  But if you want to include
259 some files in an installed version of Org: simply specify in the
260 customization variable =ORG_ADD_CONTRIB= which files you want
261 included, then build and install in the usual way.  Your =local.mk=
262 default customization template has a commented out example for
263 including the new exporter, you just need to remove the comment
264 marker:
265
266 #+BEGIN_SRC makefile-gmake
267   # Define if you want to include some (or all) files from contrib/lisp
268   # just the filename please (no path prefix, no .el suffix), maybe with globbing
269   ORG_ADD_CONTRIB = ox-* # e.g. the contributed exporter
270 #+END_SRC
271
272 You just give the base name of the file to include (much like you do
273 in a =require= form), only that you can use a shell globbing pattern
274 to specify many similar names at ones.  You do not need to specify the
275 path prefix =contrib/lisp/= nor the file suffix =.el=, these are added
276 by the build system.  To include all of =contrib/lisp/= (some of these
277 aren't really meant to be used together, so this isn't recommended)
278 you'd say:
279
280 #+BEGIN_SRC makefile-gmake
281   ORG_ADD_CONTRIB = org* ox*
282 #+END_SRC
283
284 Or if that was just a one-time install (with quoting for a POSIX
285 shell):
286
287 : make ORG_ADD_CONTRIB="ox-*" install
288
289 Note: A simple =*= would also include =htmlize.el=, which is currently
290 bundled in contrib.  It is recommended to install that seperately, it
291 is available for instance in GNU ELPA.
292
293 *** Non-standard Emacs location
294
295 Customization for using a self-compiled Emacs 24 installed in
296 =/usr/local= and the default target changed to =up2=.  Additional
297 customization to enable htmlize installed from ELPA in users' home
298 directory and ESS (for R) in the system =/usr/share/emacs/site-lisp/=
299 and all Babel languages activated for testing.
300
301 #+BEGIN_SRC makefile-gmake
302   up2::   # default target
303   EMACS   = /usr/local/bin/emacs-24.3
304   prefix  = /usr/local/share
305   lispdir = $(prefix)/emacs/site-lisp/org
306   datadir = $(prefix)/emacs/etc/org
307   infodir = $(prefix)/info
308   
309   BTEST_EXTRA = ess-site 
310   BTEST_OB_LANGUAGES = awk C fortran maxima lilypond octave python sh R
311   BTEST_POST = -L ~/.emacs.d/elpa/htmlize-1.39 \
312                -L /usr/share/emacs/site-lisp/emacs-ess-12.04.4
313 #+END_SRC
314
315 *** XEmacs
316
317 Customization for using XEmacs 21.5, since there seems to be no ERT
318 for XEmacs testing will not work and has been disabled.  The default
319 target is set to =up0 doc uncompiled= (pull from Git and update
320 documentation and autoload files).
321
322 #+BEGIN_SRC makefile-gmake
323   .PHONY: xemacs
324   xemacs: up0 doc uncompiled
325   EMACS   = xemacs
326   prefix  = /usr/local/share
327   lispdir = $(prefix)/xemacs/site-lisp/org
328   datadir = $(prefix)/xemacs/etc/org
329   infodir = $(prefix)/info
330   
331   BTEST = /bin/true
332   BATCH = $(EMACS) -batch -q -vanilla # XEmacs
333   # How to byte-compile the whole source directory
334   ELCDIR  = $(BATCH) \
335                   --eval '(add-to-list '"'"'load-path ".")' \
336                   --eval '(byte-recompile-directory "." 0)'
337 #+END_SRC
338
339 *** Emacs on Windows
340
341 Customization for using vanilla Emacs 24 on Windows, with GNU make and
342 other binaries provided by Cygwin.  Make sure the installation path(s)
343 contain no spaces!  Use the 8.3 compatible names, e.g. =PROGRA~1=
344 instead of "Program Files", if you already installed the applications
345 in such a location. Babel languages have been stripped down for
346 testing and the default target is again set to =up2=.
347
348 #+BEGIN_SRC makefile-gmake
349   up2::
350   CYGWIN += nodosfilewarning
351   prefix  = C:/Freeware/Emacs-24.3
352   EMACS   = SHELL=sh $(prefix)/bin/emacs
353   lispdir = $(prefix)/site-lisp/org
354   datadir = $(prefix)/etc/org
355   infodir = $(prefix)/info
356   
357   BTEST_OB_LANGUAGES = octave
358   SUDO =
359 #+END_SRC
360
361 ** Advanced Customization
362 *** Compilation Methods
363
364 The default compilation method compiles all source files within the
365 same Emacs process, simply because that is the fastest method.
366 Unfortunately, Emacs does not isolate the side-effects of compilations
367 from each other, so the byte compiler may not issue some errors or
368 warnings (mostly about missing declarations or requires).  To enable
369 developers to catch these errors, different compilation methods can be
370 configured by defining =ORGCM= to one of these values (either
371 permanently in =local.mk= or for a single invocation of =make=):
372
373 - =dirall= :: The default compilation method, invoked via =ELCDIR=.
374 - =single= :: Uses a separate Emacs for each compilation, invoked via
375               =ELC=.
376 - =source= :: Uses a separate Emacs for each compilation invoked via
377               =ELC=.  Removes all =*.elc= files before and each
378               =*.elc= file directly after compilation so that all
379               requires are also loaded from source.  Recompiles via
380               =dirall= at the end so that all the =*.elc= files exist.
381 - =slint1= :: First compiles using =dirall=, then compiles each file
382               again using =single=.
383 - =slint2= :: First compiles via =source= and then again via =slint1=.
384
385 Both =ELCDIR= and =ELC= are also customizable, but changing their
386 definitions must not alter the semantics of compilation.  You have
387 been warned.
388
389 *** Multiple Emacsen
390
391 **** Method 1
392
393 If you're a developer (or a system administrator that serves a diverse
394 set of users) you'll likely have to deal with the need to build and
395 test Org for different versions of Emacs.  Having to copy or link the
396 correct customization file to =local.mk= quickly loses the appeal and
397 is error prone.  Here's a (hopefully better) suggestion: put each
398 customization into a file named =local-<pattern>.mk= and create a
399 =local.mk= that looks like this:
400
401 #+BEGIN_SRC makefile-gmake
402   ifdef LOCALMK
403     include local-$(LOCALMK).mk
404   else
405     include local-emacs24.mk
406   endif
407 #+END_SRC
408
409 Now switching between your different customizations is as easy as
410 : make LOCALMK=emacs23
411 (which assumes that there is a customization file =local-emacs23.mk=
412 available).
413
414 **** Method 2
415
416 If you need a more flexible structure, say to test different versions
417 of Emacs with different configurations, then you quickly end up with
418 lots of customization files.  Worse, if you then need to change a
419 customization that has been copied into many such files, you'll have
420 to remember to change it in all of them.  The idea from Method 1 can
421 be extended to split the name into different parts and then use these
422 parts seperately to customize a single aspect only.  To keep this
423 tidy, you can put all of these files into a directory =localmk= under
424 control of Git and maybe even register it as a submodule in your local
425 branch of the Org repository.
426
427 #+CAPTION: local.mk
428 #+BEGIN_SRC makefile-gmake
429   LOCALMK ?= loc
430   # split into words
431   _LMK_:=$(subst -, ,$(LOCALMK))
432   # what's the current trunk?
433   _LMK_:=$(subst trunk,24.3.50,$(_LMK_))
434   # specific Emacs version requested?
435   _VER_:=$(filter 2%,$(_LMK_))
436   ifdef _VER_
437     _LMK_:=$(subst $(_VER_),loc,$(_LMK_))
438     _MAJ_:=$(word 1,$(subst ., ,$(_VER_)))
439     _VER_:=$(_VER_:2%=-2%)
440   else
441     _MAJ_:=24
442   endif
443   # lets us just specify which emacs to use
444   ifeq ($(words $(_LMK_)),1)
445     _LMK_+=testall tmp extra
446   endif
447   ifneq ($(origin DEBUG),undefined)
448     $(info LMK[$(words $(_LMK_))]: $(_LMK_))
449     $(info VER: $(_VER_) major $(_MAJ_))
450   endif
451   # remember this file is used from the org-mode directory via link,
452   # so we have to prepend localmk/
453   $(foreach part,$(subst -, ,$(_LMK_)),$(eval include localmk/$(part).mk))
454 #+END_SRC
455
456 So, what does this do?  First, it splits =LOCALMK= on =-= characters.
457 It then checks if something looks like an Emacs version number and
458 tries to make sense of that, otherwise it's using a default version.
459 If it only got an Emacs version to use, it tacks on a default set of
460 standard customizations: =testall=, =tmp=, =extra=.  Finally, it
461 includes each of the customization files it inferred from =LOCALMK= to
462 arrive at the final customization.
463
464 #+CAPTION: loc.mk
465 #+BEGIN_SRC makefile-gmake
466   # Name of your emacs binary
467   EMACS   := /usr/local/bin/emacs$(_VER_)
468   
469   # Where local software is found
470   prefix  := /usr/local/share
471   
472   # Where local lisp files go.
473   lispdir := $(prefix)/emacs/site-lisp/org
474   
475   # Where local data files go.
476   datadir := $(prefix)/emacs/etc/org
477   
478   # Where info files go.
479   infodir := $(prefix)/info
480 #+END_SRC
481
482 #+CAPTION: testall.mk
483 #+BEGIN_SRC makefile-gmake
484   BTEST_OB_LANGUAGES = perl awk C fortran maxima lilypond octave perl python sh
485   BTEST_POST = --eval '(add-to-list '"'"'load-path "~/.emacs.d/elpa/htmlize-1.39")'
486   ifeq ($(_MAJ_),24)
487     BTEST_EXTRA += ess-site
488     BTEST_OB_LANGUAGES += R
489     BTEST_POST += --eval '(add-to-list '"'"'load-path "/usr/share/emacs/site-lisp/emacs-ess-12.04.4")'
490   else
491     BTEST_PRE += --eval '(add-to-list '"'"'load-path "testing/ert")'
492   endif
493 #+END_SRC
494
495 #+CAPTION: tmp.mk
496 #+BEGIN_SRC makefile-gmake
497   # where to create temporary files for the testsuite
498   TMPDIR ?= /tmp
499   testdir = $(TMPDIR)/tmp-orgtest
500 #+END_SRC
501
502 #+CAPTION: extra
503 #+BEGIN_SRC makefile-gmake
504   # extra targets
505   .PHONY: testclean
506   testclean:      test clean
507 #+END_SRC
508
509 #+CAPTION: testmin.mk
510 #+BEGIN_SRC makefile-gmake
511   BTEST_OB_LANGUAGES = 
512   BTEST_POST = --eval '(add-to-list '"'"'load-path "~/.emacs.d/elpa/htmlize-1.39")'
513   ifneq ($(_MAJ_),24)
514     BTEST_PRE += --eval '(add-to-list '"'"'load-path "testing/ert")'
515   endif
516 #+END_SRC
517
518 * Support for Installers
519
520 The Org build system supports staged installs via =DESTDIR=.  If
521 =DESTDIR= is defined as a non-empty string (it really should be a
522 leading path and end with a path separator), the actual installation
523 paths are all prepended by the expansion of =DESTDIR=.  Except for
524 install and testing, the build does not write outside the build
525 directory and both of these can be customized to stay within the build
526 directory also.
527
528 * Support for Manual Build
529
530 Since GNU make or some programs used by the build system might not be
531 available on some systems, the core functionality has been implemented
532 or replicated in Emacs Lisp with no dependencies on external tools.  The
533 supported functions are: =org-make-autoloads=,
534 =org-make-autoloads-compile= and =org-make-autoloads-compile-force=.
535 All other interfaces should be considered private and are subject to
536 change without notice.  The commands assume that the current working
537 directory is at the toplevel of the Org build directory (i.e. where
538 you'll find =mk/default.mk=).
539
540 To make the autoloads file:
541 : emacs -batch -Q -L lisp -l ../mk/org-fixup -f org-make-autoloads
542 To make the autoloads file and byte-compile Org:
543 : emacs -batch -Q -L lisp -l ../mk/org-fixup -f org-make-autoloads-compile
544 To make the autoloads file and byte-compile all of Org again:
545 : emacs -batch -Q -L lisp -l ../mk/org-fixup -f org-make-autoloads-compile-force
546
547 If =git= is also unavailable, fake version strings need to be provided.
548 : emacs -batch -Q -L lisp -l ../mk/org-fixup \
549 : --eval '(let ((org-fake-release "8.0.1")(org-fake-git-version "8.0.1-fake"))\
550 : (org-make-autoloads))'
551
552 The above assumes a POSIX shell for its quoting, Windows =CMD.exe= has
553 quite different quoting rules and this won't work.  Also, users of
554 Aquamacs have reported that the command line examples aren't working
555 for them.  Your other option is to start Emacs like this
556 : emacs -Q -L lisp -l ../mk/org-fixup
557 then paste the following into the =*scratch*= buffer:
558 #+BEGIN_SRC emacs-lisp
559   ; replace the version strings with something sensible that can't be
560   ; confused with a real Git version
561   (let ((org-fake-release     "8.0.1")
562         (org-fake-git-version "8.0.1-fake"))
563     (org-make-autoloads))
564 #+END_SRC
565
566 Execute each form by placing the cursor after the closing paren on the
567 last line and press =C-j= or =C-x C-e=.
568
569 If the command line above is still spooking you: start Emacs like you
570 normally do, then add =<orgmode>/lisp= to your load-path, then issue
571 =M-x load-library=, answer the prompt with =../mk/org-fixup.el=, then
572 do the same things in the scratch buffer as outlined above.
573
574 * Footnotes
575
576 [fn:1] The build systems' notion of "all documentation" can be
577 influenced via the configuration variable =ORG_MAKE_DOC=.
578
579 [fn:2] If you just want to re-compile all lisp sources without doing
580 anything else, you can run =make cleanelc compile-dirty=.
581
582 [fn:3] The build systems' notion of "full testsuite can be configured
583 with =BTEST_OB_LANGUAGES=.
584
585 [fn:5] The test directory is generally removed after testing, but this
586 may not happen when there are test errors.  Also, the automatic
587 removal of the test directory can be prevented (for debugging
588 purposes) by defining a variable =TEST_NO_AUTOCLEAN=.
589
590 [fn:4] The build system doesn't really know where your previous
591 installation is, of course: it tries to remove Org from where it would
592 install it, based on the current customization.  .  So if you want to
593 move your Org installation, you need to first uninstall it using the
594 old customization, then change the costomization and then do a fresh
595 install.
596