Differences

This shows you the differences between two versions of the page.

doc:devel:packages [2013/07/03 17:28]
woglinde add addtional steps for editing mk-files
doc:devel:packages [2014/09/22 18:23] (current)
karlp better headings for sections in pkg_fixup
Line 5: Line 5:
  * package/Makefile   * package/Makefile
  * package/patches   * package/patches
 +  * package/files
The patches directory is optional and typically contains bug fixes or optimizations to reduce the size of the executable. The patches directory is optional and typically contains bug fixes or optimizations to reduce the size of the executable.
 +The files directory is optional. It typically includes default config or init files.
The package makefile is the important item because it provides the steps actually needed to download and compile the package. The package makefile is the important item because it provides the steps actually needed to download and compile the package.
Line 32: Line 34:
  SECTION:=base   SECTION:=base
  CATEGORY:=Network   CATEGORY:=Network
-  DEFAULT:=y 
  TITLE:=Ethernet bridging configuration utility   TITLE:=Ethernet bridging configuration utility
  #DESCRIPTION:=This variable is obsolete. use the Package/name/description define instead!   #DESCRIPTION:=This variable is obsolete. use the Package/name/description define instead!
Line 63: Line 64:
  * PKG_VERSION    - The upstream version number that we're downloading   * PKG_VERSION    - The upstream version number that we're downloading
  * PKG_RELEASE    - The version of this package Makefile   * PKG_RELEASE    - The version of this package Makefile
 +  * PKG_LICENSE    - The license(s) the package is available under, SPDX form.
 +  * PKG_LICENSE_FILE- file containing the license text
  * PKG_BUILD_DIR  - Where to compile the package   * PKG_BUILD_DIR  - Where to compile the package
  * PKG_SOURCE      - The filename of the original sources   * PKG_SOURCE      - The filename of the original sources
-  * PKG_SOURCE_URL  - Where to download the sources from+  * PKG_SOURCE_URL  - Where to download the sources from (directory)
  * PKG_MD5SUM      - A checksum to validate the download   * PKG_MD5SUM      - A checksum to validate the download
  * PKG_CAT        - How to decompress the sources (zcat, bzcat, unzip)   * PKG_CAT        - How to decompress the sources (zcat, bzcat, unzip)
Line 71: Line 74:
  * PKG_INSTALL    - Setting it to "1" will call the package's original "make install" with prefix set to PKG_INSTALL_DIR   * PKG_INSTALL    - Setting it to "1" will call the package's original "make install" with prefix set to PKG_INSTALL_DIR
  * PKG_INSTALL_DIR - Where "make install" copies the compiled files   * PKG_INSTALL_DIR - Where "make install" copies the compiled files
 +  * PKG_FIXUP      - ???
The PKG_* variables define where to download the package from; @SF is a special keyword for downloading packages from sourceforge. The md5sum is used to verify the package was downloaded correctly and PKG_BUILD_DIR defines where to find the package after the sources are uncompressed into $(BUILD_DIR). PKG_INSTALL_DIR defines where the files will be copied after calling "make install" (set with the PKG_INSTALL variable), and after that you can package them in the install section. The PKG_* variables define where to download the package from; @SF is a special keyword for downloading packages from sourceforge. The md5sum is used to verify the package was downloaded correctly and PKG_BUILD_DIR defines where to find the package after the sources are uncompressed into $(BUILD_DIR). PKG_INSTALL_DIR defines where the files will be copied after calling "make install" (set with the PKG_INSTALL variable), and after that you can package them in the install section.
At the bottom of the file is where the real magic happens, "BuildPackage" is a macro setup by the earlier include statements. BuildPackage only takes one argument directly -- the name of the package to be built, in this case "bridge". All other information is taken from the define blocks. This is a way of providing a level of verbosity, it's inherently clear what the DESCRIPTION variable in Package/bridge is, which wouldn't be the case if we passed this information directly as the Nth argument to BuildPackage. At the bottom of the file is where the real magic happens, "BuildPackage" is a macro setup by the earlier include statements. BuildPackage only takes one argument directly -- the name of the package to be built, in this case "bridge". All other information is taken from the define blocks. This is a way of providing a level of verbosity, it's inherently clear what the DESCRIPTION variable in Package/bridge is, which wouldn't be the case if we passed this information directly as the Nth argument to BuildPackage.
 +
 +===== PKG_FIXUP =====
 +
 +Some/many packages that think autotools is a good idea end up needing "fixes" to work around autotools "accidentally" knowing better and using host tools instead of the build environment tools.  OpenWrt defines some PKG_FIXUP rules to help work around this. FIXME snarkiness probably not required
 +
 +<code make>
 +PKG_FIXUP:=autoreconf
 +PKG_FIXUP:=patch-libtool
 +PKG_FIXUP:=gettext-version
 +</code>
 +
 +Any variations of this you see in the wild are simply aliases for these.
 +
 +== autoreconf ==
 +This fixup performs
 +
 +  * autoreconf -f -i
 +  * touch required but maybe missing files
 +  * ensures that openwrt-libtool is linked
 +  * suppresses autopoint/gettext
 +
 +== patch-libtool ==
 +If the shipped automake recipes are broken beyound repair then simply find instances of libtool, detect their version and apply openwrt fix patches to it
 +
 +== gettext-version ==
 +This fixup suppress version mismatch errors in automake's gettext support
 +
 +=== Tips ===
 +
 +Packages that are using Autotools should work with simply "PKG_FIXUP:=autoreconf". However there might be issues with required versions.
 +
 +Instead of patching ./configure one should fix the file from which ./configure is generated in autotools: configure.ac / configure.in.
===== BuildPackage defines ===== ===== BuildPackage defines =====
Line 88: Line 124:
  *  DESCRIPTION - (deprecated) A long description of the package   *  DESCRIPTION - (deprecated) A long description of the package
  *  URL        - Where to find the original software   *  URL        - Where to find the original software
-  *  MAINTAINER  - (optional) Who to contact concerning the package+  *  MAINTAINER  - (required for new packages) Who to contact concerning the package
  *  DEPENDS    - (optional) Which packages must be built/installed before this package. See [[#Dependency.types|below]] for the syntax.   *  DEPENDS    - (optional) Which packages must be built/installed before this package. See [[#Dependency.types|below]] for the syntax.
 +  *  USERID      - (optional) a username:groupname pair to create at package installation time.
== Package/conffiles (optional) == == Package/conffiles (optional) ==
Line 113: Line 150:
== Build/Compile (optional) == == Build/Compile (optional) ==
-How to compile the source; in most cases you should leave this undefined.+How to compile the source; in most cases you should leave this undefined, because 
 +then the default is used, which calls make. If you want to pass special arguments 
 +to make, use e.g. "$(call Build/Compile/Default,FOO=bar) 
 + 
 +== Build/Install (optional) == 
 + 
 +How to install the compiled source. The default is to call make install. Again, to 
 +pass special arguments or targets, use $(call Build/Install/Default,install install-foo) 
 +Note that you need put all the needed make arguments here. If you just need to add 
 +something to the "install" argument, don't forget the 'install' itself. 
 + 
 +== Build/InstallDev (optional) == 
 + 
 +For things needed to compile packages against it (static libs, header files), but that are of no use on the target device.
== Package/install == == Package/install ==
-A set of commands to copy files out of the compiled source and into the ipkg +A set of commands to copy files into the ipkg which is represented by the $(1) directory
-which is represented by the $(1) directory.+As source you can use relative paths which will install from the unpacked and compiled 
 +source, or $(PKG_INSTALL_DIR) which is where the files in the Build/Install step above end up.
== Package/preinst == == Package/preinst ==
Line 164: Line 215:
| BROKEN | Package doesn't build or work, and should only be visible if "Show broken targets/packages" is selected. Prevents the package from failing builds by accidentally selecting it. | | BROKEN | Package doesn't build or work, and should only be visible if "Show broken targets/packages" is selected. Prevents the package from failing builds by accidentally selecting it. |
| IPV6 | IPv6 support in packages is selected. | | IPV6 | IPv6 support in packages is selected. |
 +
 +===== Configure a package source =====
 +
 +Example:
 +<code>
 +CONFIGURE_ARGS += \
 +        --disable-native-affinity \
 +        --disable-unicode \
 +        --enable-hwloc
 +
 +CONFIGURE_VARS += \
 +        ac_cv_file__proc_stat=yes \
 +        ac_cv_file__proc_meminfo=yes \
 +        ac_cv_func_malloc_0_nonnull=yes \
 +        ac_cv_func_realloc_0_nonnull=yes
 +
 +</code>
 +To set variables (autoconfig internal ones or CPPFLAGS,CFLAGS, CXXFLAGS, LDFLAGS for example) or configure arguments.
 +Setting configure arguments is common. Setting VARS is needed when the configure.ac autoconf source script does not work well on cross compilation or finding libraries.
 +
 +==== Host tools required ====
 +If your package needs some private tools built on the host, you can use the following snippet as a pointer of where to look for more info
 +
 +<code make>
 +HOST_BUILD_DEPENDS:=<packagename>/host
 +PKG_BUILD_DEPENDS:=<packagename>/host
 +include $(INCLUDE_DIR)/host-build.mk
 +
 +define Host/Compile
 +define Host/Install
 +
 +$(eval $(call HostBuild))
 +</code>
 +TODO Expand on how to use this, and include examples
 +
 +FIXME
 +
 +Extracted from this thead on the devel mailing list: https://lists.openwrt.org/pipermail/openwrt-devel/2014-February/023970.html
== NOTES == == NOTES ==
Line 261: Line 350:
$(CP) $(PKG_BUILD_DIR)/input_uvc.so $(1)/usr/lib $(CP) $(PKG_BUILD_DIR)/input_uvc.so $(1)/usr/lib
endif endif
 +
 +===== Working on local application source =====
 +If you are still working on the application itself, at the same time as you are working on the packaging, it can be very useful to have OpenWrt build your work in progress code, rather than a specific version+md5sum combination checked out of revision control, or downloaded from your final "release" location.  There are a few ways of doing this.
 +
 +==== CONFIG_SRC_TREE_OVERRIDE ====
 +This is an option in menuconfig. See "Advanced configuration options (for developers)" -> "Enable package source tree override"
 +
 +This allows you to point to a local git tree.  (And only git)  Say your package is defined in my_cool_feed/awesome_app.
 +<code>
 +ln -s /path/to/local/awesome_app_tree/.git feeds/my_cool_feed/awesome_app/git-src
 +make package/awesome_app/{clean,compile} V=s
 +</code>
 +
 +Benefits of this approach are that you don't need any special infrastructure in your package makefiles, they stay completely as they would be for a final build. The downside is that it only builds whatever is currently _committed_ in HEAD of your local tree.  (Not <em>master</em>, this could be a private testing branch, but it must be <em>committed</em> it can't be local changes)
 +This will also use a _separate_ directory for building and checking out the code.  So any built objects in your local git tree (for example, build targeting a different architecture) will be left alone, but whatever _branch_ is checked out in your tree determines where HEAD is.
 +
 +==== USE_SRC_DIR ====
 +
 +As part of deprecating package-version-override.mk (below) a method to point directly to local source was introduced.
 +<code>
 +make package/awesome_app/clean V=s
 +make package/awesome_app/prepare USE_SOURCE_DIR=~/src/awesome_src V=s
 +make package/awesome_app/clean V=s
 +</code>
 +(V=s is optional above)
 +
 +This doesn't require any config change to enable rules, and doesn't require that you have a local git tree, and doesn't require any files to be committed.
 +
 +At least at present however, this has the following problems:
 +  * make clean doesn't clean the source link directory, but still seems to be removing a link
 +  * make prepare needs to be run every time
 +  * make package/awesome_app/{clean,compile} USE_SOURCE_DIR=~blah doesn't work
 +  * Seems to have bad interactions with leaving USE_SOURCE_DIR set for other (dependent?) packages.
 +
 +See http://www.mail-archive.com/openwrt-devel@lists.openwrt.org/msg23122.html for the original discussion of this new feature
 +
 +==== (Deprecated) package-version-override.mk ====
 +:!: ** Don't use this anymore **
 +Support for this style of local source building was removed in: https://dev.openwrt.org/changeset/40392.  This style required a permanent modification to your package makefile, and then entering a path via menuconfig to where the source was found.  It was fairly easy to use, and didn't care whether your local source was in git or svn or visual source safe even, but it had the major downside that the "clean" target simply didn't work.  (As it simply removed a symlink for cleaning)
 +
 +If you build a current OpenWrt tree, with packages that still attempt to use this style of local building, you _will_ receive errors like so:
 +ERROR: please fix package/feeds/feed_name/application_name/Makefile - see logs/package/feeds/feed_name/application_name/dump.txt for details
 +
 +If you need/want to keep using this style, where it's available, make sure you include without failing if it was missing:
 +<code>
 +-include $(INCLUDE_DIR)/package-version-override.mk
 +</code>
Line 272: Line 408:
See //**FIX:Customizingthekerneloptions customizing the kernel options**// for including it in the kernel. See //**FIX:Customizingthekerneloptions customizing the kernel options**// for including it in the kernel.
-To include one of these programs as a loadable module, select the corresponding kernel option in the OpenWrt configuration (see [[doc:howto:build#configuration|Build Configuration]]). If your favorite kernel module does not appear in the OpenWrt configuration menus, you must add a stanza to one of the files in the package/kernel/modules directory. Here is an example extracted from package/kernel/modules/block.mk:+To include one of these programs as a loadable module, select the corresponding kernel option in the OpenWrt configuration (see [[doc:howto:build#configuration|Build Configuration]]). If your favorite kernel module does not appear in the OpenWrt configuration menus, you must add a stanza to one of the files in the package/kernel/linux/modules directory. Here is an example extracted from .../modules/block.mk:
<code> <code>
define KernelPackage/loop define KernelPackage/loop
Line 291: Line 427:
</code> </code>
-With latest svn/trunk version changes to .mk-files are not seen immediately. Known workaround is to call +Changes to the *.mk files are not automatically picked up by the build system. To force re-reading the meta data either touch the kernel package Makefile using ''touch package/kernel/linux/Makefile'' (on older revisions ''touch package/kernel/Makefile'') or to delete the ''tmp/'' directory of the buildroot. 
-<code> + 
- rm package/kernel/Makefile; touch package/kernel/linux/Makefile +You can also add kernel modules which are //not// part of the linux source distribution. In this case, a kernel module appears in the package/ directory, just as any other package does. The package/Makefile uses <code>KernelPackage/xxx</code> definitions in place of <code>Package/xxx</code> 
-</code> +For example, here is package/madwifi/Makefile:
-You can also add kernel modules which are //not// part of the linux source distribution. In this case, a kernel module appears in the package/ directory, just as any other package does. The package/Makefile uses <code>KernelPackage/xxx</code> +
- definitions in place of <code>Package/xxx</code> +
-. For example, here is package/madwifi/Makefile:+
<code> <code>
# #
Line 493: Line 626:
Very basic example of a suitable init.d script Very basic example of a suitable init.d script
 +
 +:!: **procd** style init is used in some init.d scripts since: https://dev.openwrt.org/changeset/38023 .
 +See http://wiki.openwrt.org/inbox/procd-init-scripts for more details on that
 +
<code> <code>
#!/bin/sh /etc/rc.common #!/bin/sh /etc/rc.common
 +# "new(er)" style init script
 +# Look at /lib/functions/service.sh on a running system for explanations of what other SERVICE_
 +# options you can use, and when you might want them.
 +
 +START=80
 +APP=mrelay
 +SERVICE_WRITE_PID=1
 +SERVICE_DAEMONIZE=1
 +
 +start() {
 +        service_start /usr/bin/$APP
 +}
 +
 +stop() {
 +        service_stop /usr/bin/$APP
 +}
 +</code>
 +
 +<code>
 +#!/bin/sh /etc/rc.common
 +###########################################
 +# NOTE - this is an old style init script #
 +###########################################
START=80 START=80
Line 511: Line 671:
===== How To Submit Patches to OpenWrt ===== ===== How To Submit Patches to OpenWrt =====
 +Packages are maintained in a separate repository to reduce maintennance overhead.  The general guidelines for OpenWrt still apply, but see the README in the packages repository for latest information.
 +
 +  * https://github.com/openwrt/packages
  * https://dev.openwrt.org/wiki/SubmittingPatches   * https://dev.openwrt.org/wiki/SubmittingPatches
 +
 +See https://lists.openwrt.org/pipermail/openwrt-devel/2014-June/025810.html for the original announcement of this change

Back to top

doc/devel/packages.1372865320.txt.bz2 · Last modified: 2013/07/03 17:28 by woglinde