0abdddfc2c9e4b2961b36b31b224d3c206617543
[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
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
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
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
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
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
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 #+NAME: local.mk
428 #+BEGIN_SRC Makefile
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 #+NAME: loc.mk
465 #+BEGIN_SRC Makefile
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 #+NAME: testall.mk
483 #+BEGIN_SRC Makefile
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 #+NAME: tmp.mk
496 #+BEGIN_SRC Makefile
497 # where to create temporary files for the testsuite
498 TMPDIR ?= /tmp
499 testdir = $(TMPDIR)/tmp-orgtest
500 #+END_SRC
501
502 #+NAME: extra
503 #+BEGIN_SRC Makefile
504 # extra targets
505 .PHONY: testclean
506 testclean:      test clean
507 #+END_SRC
508
509 #+NAME: testmin.mk
510 #+BEGIN_SRC Makefile
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