contrib/src/README

   1 Writing rules
   2 ==============
   3
   4 At the bare minimum, a package in contrib must provide two Makefile
   5 targets in src/foo/rules.mak:
   6  - .foo to build and install the package, and
   7  - .sum-foo to fetch or create a source tarball and verify it,
   8 where foo the package name.
   9
  10
  11 Tarball
  12 --------
  13
  14 .sum-foo typically depends on a separate target that fetches the source
  15 code. In that case, .sum-foo needs only verify that the tarball
  16 is correct, e.g.:
  17
  18
  19         $(TARBALLS)/libfoo-$(FOO_VERSION).tar.bz2:
  20                 $(call download,$(FOO_URL))
  21
  22         # This will use the default rule: check SHA-512
  23         .sum-foo: libfoo-$(FOO_VERSION).tar.bz2
  24
  25 NOTE: contrary to the previous VLC contribs, this system always uses
  26 a source tarball, even if the source code is downloaded from a VCS.
  27 This serves two purposes:
  28  - offline builds (or behind a firewall),
  29  - source code requirements compliance.
  30
  31
  32 Compilation
  33 ------------
  34
  35 Similarly, .foo typically depends on the source code directory. In this
  36 case, care must be taken that the directory name only exists if the
  37 source code is fully ready. Otherwise Makefile dependencies will break
  38 (this is not an issue for files, only directories).
  39
  40         libfoo: libfoo-$(FOO_VERSION).tar.bz2 .sum-foo
  41                 $(UNPACK) # to libfoo-$(FOO_VERSION)
  42                 ### apply patches here ###
  43                 # last command: make the target directory
  44                 $(MOVE)
  45
  46         .foo: libfoo
  47                 cd $< && $(HOSTVARS) ./configure $(HOSTCONF)
  48                 cd $< && $(MAKE) install
  49                 touch $@
  50
  51 Conditional builds
  52 -------------------
  53
  54 As far as possible, build rules should determine automatically whether
  55 a package is useful (for VLC media player) or not. Useful packages
  56 should be listed in the PKGS special variable. See some examples:
  57
  58         # FFmpeg is always useful
  59         PKGS += ffmpeg
  60
  61         # DirectX headers are useful only on Windows
  62         ifdef HAVE_WIN32
  63         PKGS += directx
  64         endif
  65
  66         # x264 is only useful when stream output is enabled
  67         ifdef BUILD_ENCODERS
  68         PKGS += x264
  69         endif
  70
  71 If a package is a dependency of another package, but it is not a
  72 direct dependency of VLC, then it should NOT be added to PKGS. The
  73 build system will automatically build it via dependencies (see below).
  74
  75 Some packages may be provided by the target system. This is especially
  76 common when building natively on Linux or BSD. When this situation is
  77 detected, the package name should be added to the PKGS_FOUND special
  78 variable. The build system will then skip building this package:
  79
  80         # Asks pkg-config if foo version 1.2.3 or later is present:
  81         ifeq ($(call need_pkg,'foo >= 1.2.3'),)
  82         PKGS_FOUND += foo
  83         endif
  84
  85 Note: The need_pkg function always return 1 during cross-compilation.
  86 This is a known bug.
  87
  88
  89 Dependencies
  90 -------------
  91
  92 If package bar depends on package foo, the special DEPS_bar variable
  93 should be defined as follow:
  94
  95         DEPS_bar = foo $(DEPS_foo)
  96
  97 Note that dependency resolution is unfortunately _not_ recursive.
  98 Therefore $(DEPS_foo) really should be specified explicitly as shown
  99 above. (In practice, this will not make any difference insofar as there
 100 are no pure second-level nested dependencies. For instance, libass
 101 depends on FontConfig, which depends on FreeType, but libass depends
 102 directly on FreeType anyway.)
 103
 104 Also note that DEPS_bar is set "recursively" with =, rather than
 105 "immediately" with :=. This is so that $(DEPS_foo) is expanded
 106 correctly, even if DEPS_foo it is defined after DEPS_bar.
 107
 108 Implementation note:
 109
 110         If you must know, the main.mak build hackery will automatically
 111         emit a dependency from .bar onto .dep-foo:
 112
 113                 .bar: .dep-foo
 114
 115         ...whereby .dep-foo will depend on .foo:
 116
 117                 .dep-foo: .foo
 118                         touch $@
 119
 120         ...unless foo was detected in the target distribution:
 121
 122                 .dep-foo:
 123                         touch $@
 124
 125         So you really only need to set DEPS_bar.