aboutsummaryrefslogtreecommitdiffstats
path: root/doc/src/guide/compat.asciidoc
blob: 8c8f935c38ce0a25bc2d83d46a5fe31573d31173 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
[[compat]]
== Compatibility with other build tools

Erlang.mk tries its best to be compatible with the other Erlang
build tools. It can use dependencies written with other build
tools in mind, and can also make your projects usable by those
build tools as well. Erlang.mk is like the cool kid that gets
along with everybody.

In this chapter I will use the term _Rebar project_ to refer
to a project built using Rebar 2, Rebar 3 or Mad. These three
build tools are very similar and share the same configuration
file.

=== Rebar projects as Erlang.mk dependencies

Erlang.mk comes with a feature called _Autoload_ which will
use Rebar 2 to patch any Rebar project and make it compatible
with Erlang.mk. This feature essentially patches Rebar out
and adds a Makefile to the project that Erlang.mk can then
use for building:

_Autoload_ is documented in more details in the
xref:deps[Packages and dependencies] chapter.

=== Erlang.mk projects as Rebar dependencies

Erlang.mk projects can be made compatible with the Rebar family
of build tools pretty easily, as Erlang.mk will generate
all the files they require for building.

The Rebar family requires two files: a 'rebar.config' file
containing compilation options and the list of dependencies,
and the application resource file, found either at
'ebin/$(PROJECT).app' or at 'src/$(PROJECT).app.src'.

==== Rebar configuration

Erlang.mk comes with a target that generates a 'rebar.config'
file when invoked:

[source,bash]
$ make rebar.config

Careful! This will build the file even if it already existed
before.

To build this file, Erlang.mk uses information it finds in
the `DEPS` and `ERLC_OPTS` variables, among others. This
means that the Rebar family builds your project much the
same way as Erlang.mk.

// @todo Sanity check chapter.
Careful though! Different build tools have different fetching
strategies. If some applications provide differing dependencies,
they might be fetched differently by other build tools. Check
the upcoming Sanity check chapter to find out how to detect such
issues.

You can automatically generate this file when you build
your application, by making it a dependency of the `app`
target:

[source,make]
----
app:: rebar.config
----

Don't forget to commit the file when it changes!

If you run into other issues, it's probably because you use a
feature specific to Erlang.mk, like the `cp` fetch method.
It could also be that we forgot to handle something! Sorry.
We are of course interested to hear about any compatibility
problems you may have, just open a ticket!

==== Application resource file

Erlang.mk has two ways to generate an application resource
file: from the information found in the Makefile, or from
the information found in the 'src/$(PROJECT).app.src' file.
Needless to say, if you have this file in your repository,
then you don't need to worry about compatibility with other
build tools.

If you don't, however, it's not much harder. Every time
Erlang.mk will compile your application, it will produce
a new 'ebin/$(PROJECT).app' file. Simply commit this file
when it changes. It will only change when you modify the
configuration, add or remove modules.