diff options
Diffstat (limited to 'docs/manual/adding-packages-handwritten.txt')
| -rw-r--r-- | docs/manual/adding-packages-handwritten.txt | 167 |
1 files changed, 167 insertions, 0 deletions
diff --git a/docs/manual/adding-packages-handwritten.txt b/docs/manual/adding-packages-handwritten.txt new file mode 100644 index 000000000..a9d247ca8 --- /dev/null +++ b/docs/manual/adding-packages-handwritten.txt @@ -0,0 +1,167 @@ +[[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. |