Adding a package to Optware ng

The best way to learn Optware-ng build system is by studying examples. This page doesn't aim to fully describe all possible issues you may encounter, but will try to give you some guidelines for what to begin with.

Refer to Contributing to Optware ng to setup a development environment.

1. Creating a new package Makefile using template

$ make make/<package>.mk

This will create make/<package>.mk, the Makefile that will be used to fetch source, configure, build, stage (if needed) and package your <package> (no pun intended). This template Makefile you created follows the following schema:

1. Source is fetched using wget
2. Configure stage uses ./configure script. This template also assumes the use of libtool (see $(PATCH_LIBTOOL) $(@D)/libtool line)
3. Package is built and installed using make

2. Filling in package info fields

Here we'll describe main fields you have to fill in in the newly created Makefile

2.1. <FOO>_URL=

This points to full URL address of the sourcecode archive

2.2. <FOO>_VERSION=

This is the sourcecode version

2.3. <FOO>_SOURCE=

The name that will be used to save the sourcecode archive in the downloads dir

2.4. <FOO>_DIR=

The top-level dir name of the sourcecode tarball

2.5. <FOO>_UNZIP=

• zcat for gunzipped tarballs
• bzcat for bzipped tarballs
• xzcat for .tar.xz archives

If the sourcecode is not a tarball, you have to modify $(<FOO>_BUILD_DIR)/.configured stage accordingly, e.g., see make/cherokee.mk

2.6. <FOO>_MAINTAINER=

This field is slightly outdated, but you can still list yourself as a maintainer if you want to

2.7. <FOO>_DESCRIPTION=

Package description

2.8. <FOO>_PRIORITY=

You usually want to leave it to optional

2.9. <FOO>_DEPENDS=

Runtime package dependencies

2.10. <FOO>_SUGGESTS=

Runtime suggestions

2.11. <FOO>_CONFLICTS=

Runtime conflicts

2.12. <FOO>_IPK_VERSION=

This should be incremented on every ipk change

2.13. <FOO>_CONFFILES=

Space separated user-editable configuration files

3. Build- and packaging-related places you should look at

3.1. <FOO>_PATCHES=

This lists the patches in the order in which they should be applied to the sourcecode. template Makefile uses $(PATCH) -d $(BUILD_DIR)/$(<FOO>_DIR) -p0 to apply the pattches. $(PATCH) is patch binary wrapper that replaces all %OPTWARE_TARGET_PREFIX% occurrences with $(TARGET_PREFIX) before passing patches to patch.

3.2. <FOO>_CPPFLAGS=, <FOO>_LDFLAGS=

Additional compilation and linking flags

3.3. $(<FOO>_BUILD_DIR)/.configured target

This rule unpacks, patches and configures the sourcecode.

3.3.1. $(MAKE) <bar>-stage <baz>-stage

Edit this line to stage the buildtime dependencies before running configure script.

3.3.2. Configure args

Check and set configure switches and/or environment variables here:

	(cd $(@D); \
		$(TARGET_CONFIGURE_OPTS) \
		CPPFLAGS="$(STAGING_CPPFLAGS) $(<FOO>_CPPFLAGS)" \
		LDFLAGS="$(STAGING_LDFLAGS) $(<FOO>_LDFLAGS)" \
		./configure \
		--build=$(GNU_HOST_NAME) \
		--host=$(GNU_TARGET_NAME) \
		--target=$(GNU_TARGET_NAME) \
		--prefix=$(TARGET_PREFIX) \
		--disable-nls \
		--disable-static \
	)

3.3.3. $(PATCH_LIBTOOL) $(@D)/libtool

Comment this line out if you package doesn't use libtool

3.4. $(<FOO>_BUILD_DIR)/.built rule

This rule builds the configured package using make

3.5. $(<FOO>_BUILD_DIR)/.staged rule

This rule is used to install the compiled package to staging dir. This is usually useful if you're building a library. You may also want to add a line to delete the staged .la file(s) if the package uses libtool:

	rm -f $(STAGING_LIB_DIR)/<lib>.la

3.6. $(<FOO>_IPK_DIR)/CONTROL/control rule

This creates the control file used to build ipk, based on the info fields you filled in earlier. You don't usually have to edit this

3.7. $(<FOO>_IPK) rule

This creates the ipk file. If install-strip make target isn't supported, or doesn't work properly, change it to install, and then add a line like this one to strip the binaries after you install them:

	$(STRIP_COMMAND) $(<FOO>_IPK_DIR)$(TARGET_PREFIX)/{<binary1>,<binary2>,..}

Also, if package uses libtool:

	find $(<FOO>_IPK_DIR)$(TARGET_PREFIX) -type f -name '*.la' -exec rm -f {} \;

4. Building your package

When you try to build you package for the first time, if using wget, you have to call make with CREATE_CHECKSUM=1 argument, which will create checksums/<packagesource>.sha512:

make <package> CREATE_CHECKSUM=1

Later on, don't forget to push this checksum to your fork before creating a pull request. Also, please test that your package builds and installs with -j10 make switch.

5. Useful examples

Here're some useful examples to look at. The list is to be appended in the future.

5.1. Python packages

• py-jinja2.mk — pure python library
• py-django.mk — pure python library that also installs binary/ies. This package also uses a different (older) version to build python25 package
• py-cryptography.mk — python wrapper around C(++) library. This package also has a host build.

5.2. Perl packages

• perl-uri.mk — pure perl module
• perl-dbd-mysql.mk — perl module that links with C(++) library

5.3. Various sourecode fetch schemes

• transmission.mk — can fetch certain sourcecode revision using subversion
• gitosis.mk — uses git clone --bare and git archive to fetch certain commit based on date
• vlc.mk — uses git to clone and checkout specific commit based on date, then executes certain package-specific code that can be executed from git worktree only git describe, and finally archives excluding '.git' dir to save space
• template-cvs.mk — fetches code using cvs. cvs is almost never used nowadays
• inferno.mk — fetches code using mercurial host build

5.4 Source configuration schemes

• template.mk — classic autoconf'ed configure script configuration
• talloc.mk — samba project homebrew waf
• 6relayd.mk — using cmake