778ba887a1be312f4af5eeed79a83069cda08e29
[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 seems
70 easier to you).  Please look at some of the [[Customization][Customization Examples]] to
71 get an idea of what is possible.
72
73 ** Second Level =Makefile=
74
75 The =Makefile= in subdirectories can be invoked from the top level only
76 since they rely on the definitions that have been made there.
77
78 ** Defaults =mk/default.mk=
79
80 *Never change anything in* =mk/default.mk= *— always do your changes in*
81  =local.mk= *!*
82
83 The defaults will work on a typical GNU/Linux system.  For system-wide
84 installation as assumed by the build system the user must be able to
85 obtain administrative privileges via sudo.  If sudo is not available,
86 the user running make must have the necessary privileges to do the
87 install (i.e. full access to the build and install directories).
88 Besides Emacs, the following programs must be available in PATH:
89
90 - find
91 - install
92 - rm
93
94 The following programs are optional, when loss of functionality can be
95 tolerated:
96
97 - install-info
98 - makeinfo
99 - texi2pdf
100 - sudo
101 - git
102
103 ** Make Targets =mk/targets.mk=
104
105 All targets that the Org build system can build are defined here.
106 Most of the actual work will be handed off to the second level of
107 =Makefile=s in their respective subdirectories.  It is possible to
108 override some parts of the build system by defining some variables.
109 This is largely untested and consequently unsupported, but may still
110 be useful in some situations.  The following variables are considered
111 stable:
112
113 - =TEST_NO_AUTOCLEAN= :: Define to a non-null value to keep the test
114      directory around for inspection.  This is mostly useful for
115      debugging the test suite.
116 - =ORGVERSION= :: Can be used to override the automatic determination
117                   of the version strings.  If you find a need to do
118                   this, it is likely a bug someplace else.  *Never
119                   define this in a customization file!*
120 - =GITVERSION= :: See =ORGVERSION=.  Please do not define it to a
121                   value that could be confused with a real Git
122                   version string.
123 - =GITSTATUS= :: See =GITVERSION=.  If this variable is defined
124                  non-null, the string ".dirty" will be appended to the
125                  Git version string, which indicates a locally
126                  modified version.
127
128 ** Utilities =mk/org-fixup.el=
129
130 This is a collection of some Emacs Lisp routines that implement basic
131 functionality of the build system.  This mainly eliminates the need
132 for some external programs and thus reduces the number of external
133 dependencies.
134
135 A few of these functions have been designed to be used from the
136 command line or even from within Emacs itself.  This is an aid for
137 manually building a working Org installation when the external
138 dependencies of the build system cannot be met.  See
139 [[Support%20for%20Manual%20Build][Support for Manual Build]].
140
141 * Make Targets
142
143 Each time you want GNU make to build something for you, you need to
144 tell it what that is: this is called a /target/ or /goal/.  For each
145 /target/, make determines the /prerequisites/ and then goes on to
146 build them in the order of dependence.  A /target/ can be an actual
147 file that GNU make should build, but more commonly it is just a
148 moniker (called a /phony target/) that has the files to build as
149 /prerequisites/.
150
151 ** Help
152
153 - =help= :: Shows a brief list of the most commonly used /targets/
154             with a short description of what they do.
155 - =targets= :: This is an alias for =help=, mandated by GNU Makefile
156                conventions.
157 - =helpall= :: Shows (almost) all /targets/ and a short description of
158                what they do.
159
160 ** Configuration Check
161
162 - =check= :: Show the main customization.
163 - =config-test= :: Show the test customization.
164 - =config-cmd= :: Show what commands will be used.
165 - =config-all= :: Show all customization.
166
167 ** Build
168
169 - =all= :: Build all of Org: byte-compile the source files and create
170            all documentation.[fn:1]
171 - =compile= :: Ensure a clean source directory and then byte-compile
172                the source files using the [[Compilation Methods][compilation method]] =dirall=
173                by default.
174 - =compile-dirty= :: Byte-compile just those sources that haven't been
175      compiled already or are newer than their byte-compiled
176      counterpart.[fn:2]
177 - =single= :: The same as =compile=, but uses the [[Compilation Methods][compilation method]]
178               =single= (unless overridden by defining =ORGCM= on the
179               command line).
180 - =autoloads= :: Create just the autoload files, but do not
181                  byte-compile anything.
182
183 ** Test
184
185 - =test= :: runs =compile= and then the full testsuite.[fn:3]
186 - =test-dirty= :: Run the full testsuite on whatever currently is
187                   available, compiled or not.
188
189 ** Installation
190
191 - =install= :: Build all of Org and install it.
192 - =install-etc= :: Install only the =etc/= part of Org.
193 - =install-lisp= :: Install only the =lisp= part of Org.
194 - =install-info= :: Build the documentation and install only the info
195                     documentation.
196
197 ** Documentation
198
199 - =doc= :: Create all documentation.[fn:1]
200 - =docs= :: An alias for =doc=.
201 - =info= :: Create only GNU Info documentation (requires GNU Makeinfo).
202 - =pdf= :: Create only PDF documentation (requires PDFTeX).
203 - =card= :: Create only the reference card (requires PDFTeX).
204 - =refcard= :: An alias for =card=.
205
206 ** Cleaning
207
208 - =clean= :: Cleans in =lisp/= and =doc/=.
209 - =cleanall= :: Cleans everything that can be cleaned, including
210                 several types of backup files, so do not use this when
211                 you have active edit sessions!
212 - =clean-install= :: Removes a previous Org installation.  The build
213      system doesn't really know where your previous installation is,
214      of course: it tries to remove Org from where it would install it,
215      based on the current customization.
216 - =cleantest= :: Removes a test directory if it exists.[fn:4]
217
218 ** Compatibility and Convenience
219
220 - =up0= :: Updates the current Git branch from upstream by doing a
221            =git pull=.
222 - =up1= :: Does =up0= and then builds and checks Org.
223 - =up2= :: Does =up1= and installs Org if there was no test error.
224 - =update= :: Does =up0= and then builds Org.  Does not test.
225 - =update2= :: Does =update= and then installs.  This is not
226                recommended, since there is no way of telling whether
227                the just built Org has errors.
228 - =uncompiled= :: Removes any bytecompiled files and then creates the
229                   autoload files.  You can then use the Git worktree
230                   almost like an installed version of Org.  Not
231                   recommended for normal use of Org.
232 - =local.mk= :: Create a customization template.  If one already
233                 exists, you need to rename or remove it first.
234
235 * Customization
236
237 Changing the behaviour of the build system to conform to your local
238 system rules is done by editing the file =local.mk=.  The standard
239 template that is created when this file does not exist offers only the
240 most common customization variables, but you are free to customize
241 anything that =mk/default.mk= offers (but you really have to know what
242 you are doing for some of this).  Remember to only change =local.mk=,
243 please.
244
245 ** Simple Customization
246 *** Default target
247
248 The /default target/ is what =make= tries to build when you don't give
249 it anything else to do.  For compatibility with the old build system,
250 a freshly created =local.mk= will have =oldorg= defined as the default
251 target.  If you remove that line entirely from =local.mk=, =all= will
252 become the default target.  But you can put any other target there
253 that you want to become the default target or even define a new one
254 (OK, that isn't simple customization anymore).
255
256 *** Including sources from =contrib/=
257
258 If you just want to try out some of the things in =contrib/=, you can
259 simply add the directory to =load-path=.  But if you want to include
260 some files in an installed version of Org, this has been more
261 difficult.  There is now an easier way to do this: simply specify in
262 the customization variable =ORG_ADD_CONTRIB= which files you want
263 included, then build and install in the usual way.  Your =local.mk=
264 default customization template has a commented out example for
265 including the new exporter, you just need to remove the comment
266 marker:
267
268 #+BEGIN_SRC Makefile
269 # Define if you want to include some (or all) files from contrib/lisp
270 # just the filename please (no path prefix, no .el suffix), maybe with globbing
271 ORG_ADD_CONTRIB = org-e-* org-md org-export # e.g. the new exporter
272 #+END_SRC
273
274 You just give the base name of the file to include (much like you do
275 in a =require= form), only that you can use a shell globbing pattern
276 to specify many similar names at ones.  You do not need to specify the
277 path prefix =contrib/lisp/= nor the file suffix =.el=, these are added
278 by the build system.  To include all of =contrib/lisp/= you'd say:
279
280 #+BEGIN_SRC Makefile
281 ORG_ADD_CONTRIB = org*
282 #+END_SRC
283
284 Or if that was just a one-time install (with quoting for POSIX shell):
285
286 : make ORG_ADD_CONTRIB="org*" install
287
288 A simple =*= would also include =htmlize.el=, which is currently
289 bundled in contrib.  It is recommended to install that seperately, it
290 is available for instance in GNU ELPA.
291
292 *** Non-standard Emacs location
293
294 Customization for using a self-compiled Emacs 24 installed in
295 =/usr/local= and the default target changed to =up2=.  Additional
296 customization to enable htmlize installed from ELPA in users' home
297 directory and ESS (for R) in the system =/usr/share/emacs/site-lisp/=
298 and all Babel languages for testing.
299
300 #+BEGIN_SRC Makefile
301 up2::   # default target
302 EMACS   = /usr/local/bin/emacs-24.1
303 prefix  = /usr/local/share
304 lispdir = $(prefix)/emacs/site-lisp/org
305 datadir = $(prefix)/emacs/etc/org
306 infodir = $(prefix)/info
307
308 BTEST_EXTRA = ess-site 
309 BTEST_OB_LANGUAGES = awk C fortran maxima lilypond octave python sh R
310 BTEST_POST = -L ~/.emacs.d/elpa/htmlize-1.39 \
311              -L /usr/share/emacs/site-lisp/emacs-ess-12.04.4
312 #+END_SRC
313
314 *** XEmacs
315
316 Customization for using XEmacs 21.5, since there seems to be no ERT
317 for XEmacs testing will not work and has been disabled.  The default
318 target is set to =up0 doc uncompiled= (pull from Git and update
319 documentation and autoload files).
320
321 #+BEGIN_SRC Makefile
322 .PHONY: xemacs
323 xemacs: up0 doc uncompiled
324 EMACS   = xemacs
325 prefix  = /usr/local/share
326 lispdir = $(prefix)/xemacs/site-lisp/org
327 datadir = $(prefix)/xemacs/etc/org
328 infodir = $(prefix)/info
329
330 BTEST = /bin/true
331 BATCH = $(EMACS) -batch -q -vanilla # XEmacs
332 # How to byte-compile the whole source directory
333 ELCDIR  = $(BATCH) \
334                 --eval '(add-to-list '"'"'load-path ".")' \
335                 --eval '(byte-recompile-directory "." 0)'
336 #+END_SRC
337
338 *** Emacs on Windows
339
340 Customization for using vanilla Emacs 24 on Windows, with GNU make and
341 other binaries provided by Cygwin.  Make sure the installation path(s)
342 contain no spaces!  Use the 8.3 compatible names, e.g. =PROGRA~1=
343 instead of "Program Files", if you already installed the applications
344 in such a location. Babel languages have been stripped down for
345 testing and the default target is again set to =up2=.
346
347 #+BEGIN_SRC Makefile
348 up2::
349 CYGWIN += nodosfilewarning
350 prefix  = C:/Freeware/Emacs-24.1
351 EMACS   = SHELL=sh $(prefix)/bin/emacs
352 lispdir = $(prefix)/site-lisp/org
353 datadir = $(prefix)/etc/org
354 infodir = $(prefix)/info
355
356 BTEST_OB_LANGUAGES = octave
357 SUDO =
358 #+END_SRC
359
360 ** Advanced Customization
361 *** Compilation Methods
362
363 The default compilation method compiles all source files within the
364 same Emacs process, simply because that is the fastest method.
365 Unfortunately, Emacs does not isolate the side-effects of compilations
366 from each other, so the byte compiler may not issue some errors or
367 warnings (mostly about missing declarations or requires).  To enable
368 developers to catch these errors, different compilation methods can be
369 configured by defining =ORGCM= to one of these values (either
370 permanently in =local.mk= or for a single invocation of =make=):
371
372 - =dirall= :: The default compilation method, invoked via =ELCDIR=.
373 - =single= :: Uses a separate Emacs for each compilation, invoked via
374               =ELC=.
375 - =source= :: Uses a separate Emacs for each compilation invoked via
376               =ELC=.  Removes all =*.elc= files before and each
377               =*.elc= file directly after compilation so that all
378               requires are also loaded from source.  Recompiles via
379               =dirall= at the end so that all the =*.elc= files exist.
380 - =slint1= :: First compiles using =dirall=, then compiles each file
381               again using =single=.
382 - =slint2= :: First compiles via =source= and then again via =slint1=.
383
384 Both =ELCDIR= and =ELC= are also customizable, but changing their
385 definitions must not alter the semantics of compilation.  You have
386 been warned.
387
388 *** Multiple Emacsen
389
390 If you're a developer (or a system administrator that serves a diverse
391 set of users) you'll likely have to deal with the need to build and
392 test Org for different versions of Emacs.  Having to copy or link the
393 correct customization file to =local.mk= quickly loses the appeal and
394 is error prone.  Here's a (hopefully better) suggestion: put each
395 customization into a file named =local-<pattern>.mk= and create a
396 =local.mk= that looks like this:
397
398 #+BEGIN_SRC Makefile
399 ifdef LOCALMK
400   include local-$(LOCALMK).mk
401 else
402   include local-emacs24.mk
403 endif
404 #+END_SRC
405
406 Now switching between your different customizations is as easy as
407 : make LOCALMK=emacs23
408 (which assumes that there is a customization file =local-emacs23.mk=
409 available).
410
411 * Support for Installers
412
413 The Org build system supports staged installs via =DESTDIR=.  If
414 =DESTDIR= is defined as a non-empty string (it really should be a
415 leading path and end with a path separator), the actual installation
416 paths are all prepended by the expansion of =DESTDIR=.  Except for
417 install and testing, the build does not write outside the build
418 directory and both of these can be customized to stay within the build
419 directory also.
420
421 * Support for Manual Build
422
423 Since GNU make or some programs used by the build system might not be
424 available on some systems, the core functionality has been implemented
425 or replicated in Emacs Lisp with no dependencies on external tools.  The
426 supported functions are: =org-make-autoloads=,
427 =org-make-autoloads-compile= and =org-make-autoloads-compile-force=.
428 All other interfaces should be considered private and are subject to
429 change without notice.  The commands assume that the current working
430 directory is at the toplevel of the Org build directory (i.e. where
431 you'll find =mk/default.mk=).
432
433 To make the autoloads file:
434 : emacs -batch -Q -L lisp -l ../mk/org-fixup -f org-make-autoloads
435 To make the autoloads file and byte-compile Org:
436 : emacs -batch -Q -L lisp -l ../mk/org-fixup -f org-make-autoloads-compile
437 To make the autoloads file and byte-compile all of Org again:
438 : emacs -batch -Q -L lisp -l ../mk/org-fixup -f org-make-autoloads-compile-force
439
440 If =git= is also unavailable, fake version strings need to be provided.
441 : emacs -batch -Q -L lisp -l ../mk/org-fixup \
442 : --eval '(let ((org-fake-release "7.8.11")(org-fake-git-version "7.8.11-fake"))\
443 : (org-make-autoloads))'
444
445 The above assumes a POSIX shell for its quoting, Windows =CMD.exe= has
446 quite different quoting rules and this won't work.  Also, users of
447 Aquamacs have reported that the command line examples aren't working
448 for them.  Your other option is to start Emacs like this
449 : emacs -Q -L lisp -l ../mk/org-fixup
450 then paste the following into the =*scratch*= buffer:
451 #+BEGIN_SRC emacs-lisp
452   ; replace the version strings with something sensible that can't be
453   ; confused with a real Git version
454   (let ((org-fake-release     "7.8.11")
455         (org-fake-git-version "7.8.11-fake"))
456     (org-make-autoloads))
457 #+END_SRC
458
459 Execute each form by placing the cursor after the closing paren on the
460 last line and press =C-j= or =C-x C-e=.
461
462 If the command line above is still spooking you: start Emacs like you
463 normally do, then add =<orgmode>/lisp= to your load-path, then issue
464 =M-x load-library=, answer the prompt with =../mk/org-fixup.el=, then
465 do the same things in the scratch buffer as outlined above.
466
467 * Footnotes
468
469 [fn:1] The build systems' notion of "all documentation" can be
470 influenced via the configuration variable =ORG_MAKE_DOC=.
471
472 [fn:2] If you just want to re-compile all lisp sources without doing
473 anything else, you can run =make cleanelc compile-dirty=.
474
475 [fn:3] The build systems' notion of "full testsuite can be configured
476 with =BTEST_OB_LANGUAGES=.
477
478 [fn:4] The test directory is generally removed after testing, but this
479 may not happen when there are test errors.  Also, the automatic
480 removal of the test directory can be prevented (for debugging
481 purposes) by defining a variable =TEST_NO_AUTOCLEAN=.
482