kumquat-buildroot/docs/manual/adding-packages-handwritten.txt

[[handwritten-tutorial]]

Manual Makefile
---------------

*NOTE: new manual makefiles should not be created, and existing manual
makefiles should be converted either to the generic, autotools or
cmake infrastructure. This section is only kept to document the
existing manual makefiles and to help understand how they work.*

------------------------
01: #############################################################
02: #
03: # libfoo
04: #
05: #############################################################
06: LIBFOO_VERSION = 1.0
07: LIBFOO_SOURCE = libfoo-$(LIBFOO_VERSION).tar.gz
08: LIBFOO_SITE = http://www.foosoftware.org/downloads
09: LIBFOO_DIR = $(BUILD_DIR)/foo-$(FOO_VERSION)
10: LIBFOO_BINARY = foo
11: LIBFOO_TARGET_BINARY = usr/bin/foo
12:
13: $(DL_DIR)/$(LIBFOO_SOURCE):
14: 	$(call DOWNLOAD,$(LIBFOO_SITE)/$(LIBFOO_SOURCE))
15:
16: $(LIBFOO_DIR)/.source: $(DL_DIR)/$(LIBFOO_SOURCE)
17: 	$(ZCAT) $(DL_DIR)/$(LIBFOO_SOURCE) | tar -C $(BUILD_DIR) $(TAR_OPTIONS) -
18: 	touch $@
19:
20: $(LIBFOO_DIR)/.configured: $(LIBFOO_DIR)/.source
21: 	(cd $(LIBFOO_DIR); rm -rf config.cache; \
22: 		$(TARGET_CONFIGURE_OPTS) \
23: 		$(TARGET_CONFIGURE_ARGS) \
24: 		./configure \
25: 		--target=$(GNU_TARGET_NAME) \
26: 		--host=$(GNU_TARGET_NAME) \
27: 		--build=$(GNU_HOST_NAME) \
28: 		--prefix=/usr \
29: 		--sysconfdir=/etc \
30: 	)
31: 	touch $@
32:
33: $(LIBFOO_DIR)/$(LIBFOO_BINARY): $(LIBFOO_DIR)/.configured
34: 	$(MAKE) CC=$(TARGET_CC) -C $(LIBFOO_DIR)
35:
36: $(TARGET_DIR)/$(LIBFOO_TARGET_BINARY): $(LIBFOO_DIR)/$(LIBFOO_BINARY)
37: 	$(MAKE) DESTDIR=$(TARGET_DIR) -C $(LIBFOO_DIR) install-strip
38: 	rm -Rf $(TARGET_DIR)/usr/man
39:
40: libfoo: uclibc ncurses $(TARGET_DIR)/$(LIBFOO_TARGET_BINARY)
41:
42: libfoo-source: $(DL_DIR)/$(LIBFOO_SOURCE)
43:
44: libfoo-clean:
45: 	$(MAKE) prefix=$(TARGET_DIR)/usr -C $(LIBFOO_DIR) uninstall
46: 	-$(MAKE) -C $(LIBFOO_DIR) clean
47:
48: libfoo-dirclean:
49: 	rm -rf $(LIBFOO_DIR)
50:
51: #############################################################
52: #
53: # Toplevel Makefile options
54: #
55: #############################################################
56: ifeq ($(BR2_PACKAGE_LIBFOO),y)
57: TARGETS += libfoo
58: endif
------------------------

First of all, this Makefile example works for a package which
comprises a single binary executable. For other software, such as
libraries or more complex stuff with multiple binaries, it must be
qqadapted. For examples look at the other +*.mk+ files in the
+package+ directory.

At lines 6-11, a couple of useful variables are defined:

* +LIBFOO_VERSION+: The version of 'libfoo' that should be downloaded.

* +LIBFOO_SOURCE+: The name of the tarball of 'libfoo' on the download
  website or FTP site. As you can see +LIBFOO_VERSION+ is used.

* +LIBFOO_SITE+: The HTTP or FTP site from which 'libfoo' archive is
  downloaded. It must include the complete path to the directory where
  +LIBFOO_SOURCE+ can be found.

* +LIBFOO_DIR+: The directory into which the software will be
  configured and compiled. Basically, it's a subdirectory of
  +BUILD_DIR+ which is created upon decompression of the tarball.

* +LIBFOO_BINARY+: Software binary name. As said previously, this is
  an example for a package with a single binary.

* +LIBFOO_TARGET_BINARY+: The full path of the binary inside the
  target filesystem.  Lines 13-14 define a target that downloads the
  tarball from the remote site to the download directory (+DL_DIR+).

Lines 16-18 define a target and associated rules that uncompress the
downloaded tarball. As you can see, this target depends on the tarball
file so that the previous target (lines 13-14) is called before
executing the rules of the current target. Uncompressing is followed
by 'touching' a hidden file to mark the software as having been
uncompressed. This trick is used everywhere in a Buildroot Makefile to
split steps (download, uncompress, configure, compile, install) while
still having correct dependencies.

Lines 20-31 define a target and associated rules that configure the
software. It depends on the previous target (the hidden +.source+
file) so that we are sure the software has been uncompressed. In order
to configure the package, it basically runs the well-known
+./configure+ script. As we may be doing cross-compilation, +target+,
+host+ and +build+ arguments are given. The prefix is also set to
+/usr+, not because the software will be installed in +/usr+ on your
host system, but because the software will be installed in + /usr+ on
the target filesystem. Finally it creates a +.configured+ file to mark
the software as configured.

Lines 33-34 define a target and a rule that compile the software. This
target will create the binary file in the compilation directory and
depends on the software being already configured (hence the reference
to the +.configured+ file).  It basically runs +make+ inside the
source directory.

Lines 36-38 define a target and associated rules that install the
software inside the target filesystem. They depend on the binary file
in the source directory to make sure the software has been
compiled. They use the +install-strip+ target of the software
+Makefile+ by passing a +DESTDIR+ argument so that the +Makefile+
doesn't try to install the software in the host +/usr+ but rather in
the target +/usr+. After the installation, the +/usr/man + directory
inside the target filesystem is removed to save space.

Line 40 defines the main target of the software — the one that
will eventually be used by the top level +Makefile+ to download,
compile, and then install this package. This target should first of
all depend on all needed dependencies of the software (in our example,
'uclibc' and 'ncurses') and also depend on the final binary. This last
dependency will call all previous dependencies in the correct order.

Line 42 defines a simple target that only downloads the code
source. This is not used during normal operation of Buildroot, but is
needed if you intend to download all required sources at once for
later offline build. Note that if you add a new package, providing a
+libfoo-source+ target is 'mandatory' to support users that wish to do
offline-builds. Furthermore, it eases checking if all package-sources
are downloadable.

Lines 44-46 define a simple target to clean the software build by
calling the Makefile with the appropriate options.  The +-clean+
target should run +make clean+ on $(BUILD_DIR)/package-version and
MUST uninstall all files of the package from $(STAGING_DIR) and from
$(TARGET_DIR).

Lines 48-49 define a simple target to completely remove the directory
in which the software was uncompressed, configured and compiled. The
+-dirclean+ target MUST completely rm $(BUILD_DIR)/ package-version.

Lines 51-58 add the target +libfoo+ to the list of targets to be
compiled by Buildroot, by first checking if the configuration option
for this package has been enabled using the configuration tool. If so,
it then "subscribes" this package to be compiled by adding
the package to the TARGETS global variable.  The name added to the
TARGETS global variable is the name of this package's target, as
defined on line 40, which is used by Buildroot to download, compile,
and then install this package.