this repo has no description
anil.recoil.org
1opam-version: "2.0"
2maintainer: "Markus Mottl <markus.mottl@gmail.com>"
3authors: [ "Markus Mottl <markus.mottl@gmail.com>" ]
4license: "LGPL-2.1-or-later WITH OCaml-LGPL-linking-exception"
5homepage: "https://mmottl.github.io/ocaml-makefile"
6dev-repo: "git+https://github.com/mmottl/ocaml-makefile.git"
7bug-reports: "https://github.com/mmottl/ocaml-makefile/issues"
8
9build: ["mkdir" "-p" "%{lib}%/ocaml-makefile"]
10
11install: ["cp" "OCamlMakefile" "%{lib}%/ocaml-makefile"]
12
13remove: ["rm" "%{lib}%/ocaml-makefile/OCamlMakefile"]
14synopsis:
15 "A Simple Generic Makefile for [OCaml](http://www.ocaml.org)-Projects"
16description: """
17### Prerequisites
18
19 * GNU-Make version 3.80 or higher
20
21### Pros
22
23 * It is well-tested across multiple platforms and has been used in many
24 projects.
25
26 * It generates dependencies correctly by ensuring that all automatically
27 generated OCaml-files exist before dependency calculation. This is the
28 only way to guarantee that `ocamldep` can do its job.
29
30 * Convenience. Even fairly complex compilation processes (see example
31 `calc.ml`) need only little information to work correctly, sometimes
32 just about the minimum (filenames of sources).
33
34### Cons
35
36 * It may not be a good choice in projects where many compilation units
37 require different flags.
38
39 * Though it can scale to medium-sized projects, large projects with,
40 for example, dependencies across multiple libraries in different
41 directories are not well-supported.
42
43 This is a general shortcoming of the already somewhat dated `make`.
44 You may want to investigate the following tools to approach larger
45 projects:
46
47 * [jbuilder](https://github.com/janestreet/jbuilder)
48 * [OMake](http://omake.metaprl.org/index.html)
49 * [Ocamlbuild](https://ocaml.org/learn/tutorials/ocamlbuild)
50 * [Oasis](http://oasis.forge.ocamlcore.org)
51
52### Usage
53
54It is recommended that first-time users take a look at the examples in the
55distribution for a quick introduction. `OCamlMakefile`-projects are often so
56simple that they are self-explanatory.
57
58To create your own project, first edit a project-specific `Makefile` in the
59appropriate directory. There are two ways of making use of `OCamlMakefile`:
60
61 1. Have a look at the default settings in `OCamlMakefile` and set
62 them to the values that are valid on your system. For example, check
63 whether the path to the standard libraries is ok, what executables shall
64 be used, etc. Copy it into the directory of the project to be compiled.
65 Add the following statement as last line to your `Makefile`:
66
67 ```makefile
68 -include OCamlMakefile
69 ```
70
71 2. Put `OCamlMakefile` somewhere else in your system. In this case you
72 will have to set the variable `OCAMLMAKEFILE` in your project-specific
73 `Makefile`. This is the way in which the examples are written. Now you
74 only need one version of `OCamlMakefile` to manage all of your projects!
75 See the examples for details.
76
77You will usually need to specify two further variables for your project:
78
79 * `SOURCES` (default: `foo.ml`)
80 * `RESULT` (default: `foo`)
81
82Put all the sources necessary for a target into variable `SOURCES`. Then set
83`RESULT` to the name of the target. If you want to generate libraries,
84you should _not_ specify the suffix (`.cma`, `.cmxa`, `.a`). It will be
85added automatically if you specify that you want to build a library.
86
87```text
88** Don't forget to add the `.mli`-files, too! **
89** Don't forget that the order of the source files matters! **
90```
91
92The order is important, because it matters during linking due to potential
93side effects caused at program startup. This is why `OCamlMakefile` does not
94attempt to partially order dependencies by itself, which might confuse users
95even more. It just compiles and links OCaml-sources in the order specified
96by the user, even if it could determine automatically that the order cannot
97be correct.
98
99The minimum of your `Makefile` looks like this (assuming that `OCamlMakefile`
100is in the search path of `make`):
101
102```makefile
103-include OCamlMakefile
104```
105
106This will assume that you want to compile a file `foo.ml` to a binary `foo`.
107
108Otherwise, your Makefile will probably contain something like this:
109
110```makefile
111SOURCES = foo.ml
112RESULT = foo
113
114-include OCamlMakefile
115```
116
117Be careful with the names you put into these variables. If they are wrong,
118a `make clean` might erase the wrong files!
119
120A simple `make` will generate a byte-code executable. If you want to change
121this, you may add an `all`-rule that generates something else. For example:
122
123```makefile
124SOURCES = foo.ml
125RESULT = foo
126
127all: native-code-library
128
129-include OCamlMakefile
130```
131
132This will build a native-code library `foo.cmxa` (+ `foo.a`) from file
133`foo.ml`.
134
135You may even build several targets at once. To produce byte- and native-code
136executables with one `make`, add the following rule:
137
138```makefile
139all: byte-code native-code
140```
141
142You will probably want to use a different suffix for each of these targets
143so that the result will not be overwritten. See the optional variables
144below for details.
145
146You may also tell `make` at the command-line what kind of target to produce
147(e.g. `make nc`). Here all the possibilities with shortcuts between
148parenthesis:
149
150```text
151byte-code (bc)
152byte-code-nolink (bcnl) - no linking stage
153byte-code-library (bcl)
154native-code (nc)
155native-code-nolink (ncnl) - no linking stage
156native-code-library (ncl)
157debug-code (dc)
158debug-code-nolink (dcnl) - no linking stage
159debug-code-library (dcl)
160profiling-byte-code (pbc)
161profiling-byte-code-library (pbcl)
162profiling-native-code (pnc)
163profiling-native-code-library (pncl)
164byte-code-dll (bcd)
165native-code-dll (ncd)
166pack-byte-code (pabc)
167pack-native-code (panc)
168toplevel (top)
169subprojs
170```
171
172Here is a short note concerning building and linking byte code libraries
173with C-files:
174
175> OCaml links C-object files only when they are used in an executable.
176> After compilation they should be placed in some directory that is in
177> your include path if you link your library against an executable.
178>
179> It is sometimes more convenient to link all C-object files into a
180> single C-library. Then you have to override the automatic link flags
181> of your library using `-noautolink` and add another link flag that
182> links in your C-library explicitly.
183
184Concerning maintenance:
185
186 * `make clean` removes all (all!) automatically generated files.
187 So again, make sure your variables are ok!
188
189 * `make cleanup` is similar to `make clean` but keeps executables.
190
191Another way to destroy some important files is by having `OCamlMakefile`
192automatically generate files with the same name. Read the documentation about
193the tools in the OCaml-distribution to see what kind of files are generated.
194`OCamlMakefile` additionally generates (`%` is the basename of source file):
195
196 * `%_idl.c` - `camlidl` generates a file `%.c` from `%.idl`, but this is
197 not such a good idea, because when generating native-code, both the
198 file `%.c` and `%.ml` would generate files `%.o` which would overwrite
199 each other. Thus, `OCamlMakefile` renames `%.c` to `%_idl.c` to work
200 around this problem.
201
202The dependencies are stored in three different subdirectories (dot dirs):
203
204 * `._d` - contains dependencies for .ml-files
205 * `._bcdi` - contains byte code dependencies for .mli-files
206 * `._ncdi` - contains native code dependencies for .mli-files
207
208The endings of the dependency files are: `%.d` for those generated from
209`%.ml`-files and `%.di` for ones derived from `%.mli`-files.
210
211### Debugging
212
213This is easy: if you discover a bug, just do a `make clean; make dc` to
214recompile your project with debugging information. Then you can immediately
215apply `ocamldebug` to the executable.
216
217### Profiling
218
219To generate code that can be profiled with `ocamlprof` (byte code) or `gprof`
220(native code), compile your project with one of the profiling targets (see
221targets above). E.g.:
222
223 * `make pbc` will build byte code that can be profiled with `ocamlprof`.
224 * `make pnc` will build native code that can be profiled with `gprof`.
225
226Please note that it is not currently possible to profile byte code with
227threads. `OCamlMakefile` will force an error if you try to do this.
228
229A short hint for DEC Alpha-users (under Digital Unix): you may also compile
230your sources to native code without any further profiling options/targets.
231Then call `pixie my_exec`, `my_exec` being your executable. This will produce
232(among other files) an executable `my_exec.pixie`. Call it and it will produce
233profiling information which can be analyzed using `prof -pixie my_exec`.
234The resulting information is extremely detailed and allows analysis up to
235the clock cycle level...
236
237### Using Preprocessors
238
239Because any kind of program that reads from standard input and prints to
240standard output can be used as a preprocessor, there cannot be any default
241way to handle all of them correctly without further knowledge.
242
243Therefore, you have to cooperate a bit with `OCamlMakefile` to let
244preprocessing happen automatically. Basically, this only requires that you
245put a comment into the first line of files that should be preprocessed, e.g.:
246
247```ocaml
248(*pp cat *)
249(* ... rest of program ... *)
250```
251
252`OCamlMakefile` looks at the first line of your files, and if it finds a
253comment that starts with "`(*pp`", then it will assume that the rest of
254the comment tells it how to correctly call the appropriate preprocessor.
255In this case the program `cat` will be called, which will, of course, just
256output the source text again without changing it.
257
258If, for example, you were an advocate of the "revised syntax", which is
259supported by the `camlp4` preprocessor, you could simply write:
260
261```ocaml
262(*pp camlp4r *)
263(* ... rest of program in revised syntax ... *)
264```
265
266If you want to write your own syntax extensions, just take a look at the
267example in the directory `camlp4`: it implements the "`repeat ... until`"
268extension as described in the `camlp4`-tutorial.
269
270#### Library (Un-)Installation Support
271
272`OCamlMakefile` contains two targets using `ocamlfind` for this purpose:
273
274 * `libinstall`
275 * `libuninstall`
276
277These two targets require the existence of the variable `LIBINSTALL_FILES`,
278which should be set to all the files that you want to install in the
279library directory (usually %.mli, %.cmi, %.cma, %.cmxa, %.a and possibly
280further C-libraries). The target `libinstall` has the dependency `all`
281to force compilation of the library so make sure you define target `all`
282in your Makefile appropriately.
283
284The targets inform the user about the configured install path and ask for
285confirmation to (un)install there. If you want to use them, it is often a
286good idea to just alias them in your Makefile to `install` and `uninstall`
287respectively.
288
289Two other targets allow installation of files into a particular directory
290(without using `ocamlfind`):
291
292 * `rawinstall`
293 * `rawuninstall`
294
295#### Building toplevels
296
297There is just one target for this:
298
299 * `top`
300
301The generated file can be used immediately for interactive sessions - even
302with scanners, parsers, C-files, etc.!
303
304#### Generating documentation
305
306The following targets are supported:
307
308```text
309htdoc - generates HTML-documentation
310ladoc - generates Latex-documentation
311psdoc - generates PostScript-documentation
312pdfdoc - generates PDF-documentation
313doc - generates all supported forms of documentation
314clean-doc - generates all supported forms of documentation
315```
316
317All of them generate a sub-directory `doc`. More precisely, for HTML it
318is `doc/$(RESULT)/html` and for Latex, PostScript and PDF the directory
319`doc/$(RESULT)/latex`. See the OCamldoc-manual for details and the optional
320variables below for settings you can control.
321
322#### Handling subprojects
323
324You can have several targets in the same directory and manage them from
325within an single `Makefile`.
326
327Give each subproject a name, e.g. `p1`, `p2`, etc. Then you export settings
328specific to each project by using variables of the form `PROJ_p1`, `PROJ_p2`,
329etc. E.g.:
330
331```makefile
332define PROJ_p1
333 SOURCES=foo.ml main.ml
334 RESULT="p1"
335 OCAMLFLAGS="-unsafe"
336endef
337export PROJ_p1
338
339define PROJ_p2
340 ...
341endef
342export PROJ_p2
343```
344
345You may also export common settings used by all projects directly, e.g.:
346
347```makefile
348export THREADS = y
349```
350
351Now is a good time to define which projects should be affected by commands
352by default. E.g.:
353
354```makefile
355ifndef SUBPROJS
356 export SUBPROJS = p1 p2
357endif
358```
359
360This will automatically generate a given target for all those subprojects
361if this variable has not been defined in the shell environment or in the
362command line of the make-invocation by the user. E.g., `make dc` will
363generate debug code for all subprojects.
364
365Now you need to define a default action for your subprojects if `make`
366has been called without arguments:
367
368```makefile
369all: bc
370```
371
372This will build byte code by default for all subprojects.
373
374Finally, you'll have to define a catch-all target that uses the target provided
375by the user for all subprojects. Just add (assuming that OCAMLMAKEFILE has
376been defined appropriately):
377
378 %:
379 @make -f $(OCAMLMAKEFILE) subprojs SUBTARGET=$@
380
381See the `threads`-directory in the distribution for a short example!
382
383#### Optional `OCamlMakefile` variables
384
385```text
386* LIB_PACK_NAME - packs all modules of a library into a module whose
387 name is given in variable LIB_PACK_NAME.
388
389* RES_CLIB_SUF - when building a library that contains C-stubs, this
390 variable controls the suffix appended to the name of
391 the C-library (default: _stubs).
392
393* THREADS - say THREADS = yes if you need thread support compiled in,
394 otherwise leave it away.
395
396* VMTHREADS - say VMTHREADS = yes if you want to force VM-level
397 scheduling of threads (byte-code only).
398
399* ANNOTATE - say ANNOTATE = yes to generate type annotation files
400 (.annot) to support displaying of type information
401 in editors.
402
403* USE_CAMLP4 - say USE_CAMLP4 = yes in your Makefile if you
404 want to include the camlp4 directory during the build
405 process, otherwise leave it away.
406
407* INCDIRS - directories that should be searched for .cmi- and
408 .cmo-files. You need not write -I ... - just the
409 plain names.
410* LIBDIRS - directories that should be searched for libraries
411 Also just put the plain paths into this variable
412* EXTLIBDIRS - Same as LIBDIRS, but paths in this variable are
413 also added to the binary via the -R-flag so that
414 dynamic libraries in non-standard places can be found.
415* RESULTDEPS - Targets on which results (executables or libraries)
416 should additionally depend.
417
418* PACKS - adds packages under control of findlib.
419
420* PREDS - specifies findlib-predicates.
421
422* LIBS - OCaml-libraries that should be linked (just plain names).
423 E.g. if you want to link the Str-library, just write
424 str (without quotes). The new OCaml-compiler handles
425 libraries in such a way that they "remember" whether
426 they have to be linked against a C-library and it gets
427 linked in automatically. If there is a slash in the
428 library name (such as ./str or lib/foo) then make is
429 told that the generated files depend on the library.
430 This helps to ensure that changes to your libraries
431 are taken into account, which is important if you are
432 regenerating your libraries frequently.
433
434* CLIBS - C-libraries that should be linked (just plain names).
435
436* PRE_TARGETS - set this to a list of target files that you want
437 to have built before dependency calculation actually
438 takes place. E.g. use this to automatically compile
439 modules needed by camlp4, which have to be available
440 before other modules can be parsed at all.
441
442 ** WARNING **: the files mentioned in this variable
443 will be removed when make clean is executed!
444
445* LIBINSTALL_FILES - the files of a library that should be installed
446 using findlib. Default:
447
448 $(RESULT).mli $(RESULT).cmi $(RESULT).cma
449 $(RESULT).cmxa $(RESULT).a lib$(RESULT).a
450
451* OCAML_LIB_INSTALL - target directory for rawinstall/rawuninstall.
452 (default: $(OCAMLLIBPATH)/contrib)
453
454* DOC_FILES - names of files from which documentation is generated.
455 (default: all .mli-files in your $(SOURCES)).
456
457* DOC_DIR - name of directory where documentation should be stored.
458
459* OCAMLFLAGS - flags passed to the compilers
460* OCAMLBCFLAGS - flags passed to the byte code compiler only
461* OCAMLNCFLAGS - flags passed to the native code compiler only
462
463* OCAMLLDFLAGS - flags passed to the OCaml-linker
464* OCAMLBLDFLAGS - flags passed to the OCaml-linker when linking byte code
465* OCAMLNLDFLAGS - flags passed to the OCaml-linker when linking
466 native code
467
468* OCAMLMKLIB_FLAGS - flags passed to the OCaml library tool
469
470* OCAMLCPFLAGS - profiling flags passed to ocamlcp (default: a)
471
472* PPFLAGS - additional flags passed to the preprocessor
473 (default: none)
474
475* LFLAGS - flags passed to ocamllex
476* YFLAGS - flags passed to ocamlyacc
477* IDLFLAGS - flags passed to camlidl
478
479* OCAMLDOCFLAGS - flags passed to ocamldoc
480
481* OCAMLFIND_INSTFLAGS - flags passed to ocamlfind during installation
482 (default: none)
483
484* DVIPSFLAGS - flags passed to dvips
485 (when generating documentation in PostScript).
486
487* STATIC - set this variable if you want to force creation
488 of static libraries
489
490* CC - the C-compiler to be used
491* CXX - the C++-compiler to be used
492
493* CFLAGS - additional flags passed to the C-compiler.
494
495 The flag -DNATIVE_CODE will be passed automatically if
496 you choose to build native code. This allows you to
497 compile your C-files conditionally. But please note:
498 You should do a make clean or remove the object files
499 manually or touch the %.c-files: otherwise, they may
500 not be correctly recompiled between different builds.
501
502* CXXFLAGS - additional flags passed to the C++-compiler.
503
504* CPPFLAGS - additional flags passed to the C-preprocessor.
505
506* CFRAMEWORKS - Objective-C framework to pass to linker on MacOS X.
507
508* LDFLAGS - additional flags passed to the C-linker
509
510* RPATH_FLAG - flag passed through to the C-linker to set a path for
511 dynamic libraries. May need to be set by user on
512 exotic platforms. (default: -R).
513
514* ELF_RPATH_FLAG - this flag is used to set the rpath on ELF-platforms.
515 (default: -R)
516
517* ELF_RPATH - if this flag is yes, then the RPATH_FLAG will be
518 passed by -Wl to the linker as normal on ELF-platforms.
519
520* OCAMLLIBPATH - path to the OCaml-standard-libraries
521 (first default: $(OCAMLC) -where)
522 (second default: /usr/local/lib/ocaml)
523
524* OCAML_DEFAULT_DIRS - additional path in which the user can supply
525 default directories to his own collection
526 of libraries. The idea is to pass this as an
527 environment variable so that the Makefiles do not
528 have to contain this path all the time.
529
530* OCAMLFIND - ocamlfind from findlib (default: ocamlfind)
531* OCAML - OCaml interpreter (default: ocaml)
532* OCAMLC - byte-code compiler (default: ocamlc)
533* OCAMLOPT - native-code compiler (default: ocamlopt)
534* OCAMLMKTOP - top-level compiler (default: ocamlmktop)
535* OCAMLCP - profiling byte-code compiler (default: ocamlcp)
536* OCAMLDEP - dependency generator (default: ocamldep)
537
538* OCAMLLEX - scanner generator (default: ocamllex)
539 Applies to .mll files.
540
541* OCAMLYACC - parser generator (default: ocamlyacc)
542 Applies to .mly files. A good alternative to the default is
543 "menhir" if installed.
544
545* OCAMLMKLIB - tool to create libraries (default: ocamlmklib)
546* CAMLIDL - IDL-code generator (default: camlidl)
547* CAMLIDLDLL - IDL-utility (default: camlidldll)
548* CAMLP4 - camlp4 preprocessor (default: camlp4)
549* OCAMLDOC - OCamldoc-command (default: ocamldoc)
550
551* LATEX - Latex-processor (default: latex)
552* DVIPS - dvips-command (default: dvips)
553* PS2PDF - PostScript-to-PDF converter (default: ps2pdf)
554
555* CAMELEON_REPORT - report tool of Cameleon (default: report)
556* CAMELEON_REPORT_FLAGS - flags for the report tool of Cameleon
557
558* CAMELEON_ZOGGY - zoggy tool of Cameleon
559 (default: camlp4o pa_zog.cma pr_o.cmo)
560* CAMELEON_ZOGGY_FLAGS - flags for the zoggy tool of Cameleon
561
562* OCAML_GLADECC - Glade compiler for OCaml (default: lablgladecc2)
563* OCAML_GLADECC_FLAGS - flags for the Glade compiler
564
565* OXRIDL - OXRIDL-generator (default: oxridl)
566
567* NOIDLHEADER - set to yes to prohibit OCamlMakefile from using
568 the default camlidl-flag -header.
569
570* NO_CUSTOM - Prevent linking in custom mode.
571
572* QUIET - unsetting this variable (e.g. make QUIET=)
573 will print all executed commands, including intermediate
574 ones. This allows more comfortable debugging when
575 things go wrong during a build.
576
577* REALLY_QUIET - when set this flag turns off output from some commands.
578
579* OCAMLMAKEFILE - location of (= path to) this OCamlMakefile.
580 Because it calls itself recursively, it has to know
581 where it is. (default: OCamlMakefile = local directory)
582
583* BCSUFFIX - Suffix for all byte-code files. E.g.:
584
585 RESULT = foo
586 BCSUFFIX = _bc
587
588 This will produce byte-code executables/libraries with
589 basename foo_bc.
590
591* NCSUFFIX - Similar to BCSUFFIX, but for native-code files.
592* TOPSUFFIX - Suffix added to toplevel interpreters (default: .top)
593
594* SUBPROJS - variable containing the names of subprojects to be
595 compiled.
596
597* SUBTARGET - target to be built for all projects in variable
598 SUBPROJS.
599```
600
601#### Optional variables for Windows users
602
603```text
604* MINGW - variable to detect the MINGW-environment
605* MSVC - variable to detect the MSVC-compiler
606```
607
608### Contact Information and Contributing
609
610Please submit bugs reports, feature requests, contributions and similar to
611the [GitHub issue tracker](https://github.com/mmottl/ocaml-makefile/issues).
612
613Up-to-date information is available at: <https://mmottl.github.io/ocaml-makefile>"""
614depends: ["ocaml"]
615flags: light-uninstall
616url {
617 src:
618 "https://github.com/mmottl/ocaml-makefile/releases/download/6.39.0/ocaml-makefile-6.39.0.tbz"
619 checksum: [
620 "sha256=96fb83f9edc5dcda956c332c3300248463370bd1442734ee12951536fecb6277"
621 "md5=93919d9c9258bbb1f054ba506ee471da"
622 ]
623}