Differences

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

Link to this comparison view

Both sides previous revision Previous revision
Next revision		 Previous revision
docs:guide-developer:packages [2022/01/04 09:18] – Fixed typo "beyound" -> "beyond" hardfalcondocs:guide-developer:packages [2024/05/22 20:59] (current) – fix make target for package bam
Line 65: Line 65:
   * ''PKG_NAME''        - The name of the package, as seen via menuconfig and ipkg. Avoid using underscores in the package name, to avoid build failures--for example, the underscore separates name from version information, and may confuse the build system in hard-to-spot places.   * ''PKG_NAME''        - The name of the package, as seen via menuconfig and ipkg. Avoid using underscores in the package name, to avoid build failures--for example, the underscore separates name from version information, and may confuse the build system in hard-to-spot places.
   * ''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.  Should be initially set to 1, and reset to 1 whenever the ''PKG_VERSION'' is changed.  Increment it when ''PKG_VERSION'' stays the same, but when there are functional changes to the installed artifacts.
   * ''PKG_LICENSE''     - The license(s) the package is available under, [[https://spdx.org/licenses/|SPDX]] form.   * ''PKG_LICENSE''     - The license(s) the package is available under, [[https://spdx.org/licenses/|SPDX]] form.
   * ''PKG_LICENSE_FILES''- file containing the license text   * ''PKG_LICENSE_FILES''- file containing the license text
Line 71: Line 71:
   * ''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 (directory)   * ''PKG_SOURCE_URL''  - Where to download the sources from (directory)
-  * ''PKG_HASH''      - A checksum to validate the download.  It can be either a MD5 or SHA256 checksum, but SHA256 should be used, see [[https://git.lede-project.org/?p=source.git;a=blob;f=scripts/download.pl;h=90d50a88622f26f554344f20b07f9da7ba649e74;hb=HEAD#l63|scripts/download.pl]]+  * ''PKG_HASH''      - A checksum to validate the download.  It can be either a MD5 or SHA256 checksum, but SHA256 should be used, see [[commit>?p=openwrt/openwrt.git;a=blob;f=scripts/download.pl;h=676c6e9e6b10b6a44ed2bbc03a7ba3c983aaf639;hb=HEAD#l66|scripts/download.pl]]
   * ''PKG_CAT''         - How to decompress the sources (zcat, bzcat, unzip)   * ''PKG_CAT''         - How to decompress the sources (zcat, bzcat, unzip)
 +  * ''PKG_URL''.        - Upstream project homepage
   * ''PKG_BUILD_DEPENDS'' - Packages that need to be built before this package. Use this option if you need to make sure that your package has access to includes and/or libraries of another package at build time. Specify the directory name (i.e. openssl) rather than the binary package name (i.e. libopenssl). This build variable only establishes the build time dependency. Use ''DEPENDS'' to establish the runtime dependencies. This variable uses the same syntax as ''DEPENDS'' below.   * ''PKG_BUILD_DEPENDS'' - Packages that need to be built before this package. Use this option if you need to make sure that your package has access to includes and/or libraries of another package at build time. Specify the directory name (i.e. openssl) rather than the binary package name (i.e. libopenssl). This build variable only establishes the build time dependency. Use ''DEPENDS'' to establish the runtime dependencies. This variable uses the same syntax as ''DEPENDS'' below.
   * ''PKG_CONFIG_DEPENDS'' - specifies which config options influence the build configuration and should trigger a rerun of Build/Configure on change   * ''PKG_CONFIG_DEPENDS'' - specifies which config options influence the build configuration and should trigger a rerun of Build/Configure on change
Line 78: Line 79:
   * ''PKG_INSTALL_DIR'' - Where "make install" copies the compiled files   * ''PKG_INSTALL_DIR'' - Where "make install" copies the compiled files
   * ''PKG_FIXUP''       - See below   * ''PKG_FIXUP''       - See below
 +  * ''PKG_CVE_IGNORE''  - Variable for defining CVEs that don't apply to this version of the package due to features not enabled, or affecting other platforms (e.g. Windows issues or features that are not used and so not relevant)
 +  * ''PKG_CVE_FIXED''   - Variable for defining CVEs that are patches in the current version, but aren't properly marked as fixed at cve.org in the current version
  
 Optional support for fetching sources from a VCS (git, bzr, svn, etc), see [[#use_source_repository|Use source repository]] below for more information: Optional support for fetching sources from a VCS (git, bzr, svn, etc), see [[#use_source_repository|Use source repository]] below for more information:
Line 97: Line 100:
 ===== Testing a package Makefile ===== ===== Testing a package Makefile =====
  
-LEDE [[commit>?p=openwrt/openwrt.git;a=commit;h=7a315b0b5d6aa91695853a8647383876e4b49a7a|introduced]] support for a range of sanity checks like mismatched checksums.+There is [[commit>?p=openwrt/openwrt.git;a=commit;h=7a315b0b5d6aa91695853a8647383876e4b49a7a|support for a range of sanity checks]] like mismatched checksums.
  
 To check your package: To check your package:
Line 176: Line 179:
 </code> </code>
  
-Besides the source repository ''PKG_SOURCE_URL'', you also need to specify which exact version you are building using ''PKG_SOURCE_VERSION'' (e.g. a commit hash for git, or a revision number for svn)+Besides the source repository ''PKG_SOURCE_URL'', you also need to specify which exact version you are building using ''PKG_SOURCE_VERSION'' e.g. a commit hash for git, or a revision number for svn. The ''PKG_SOURCE_VERSION'' can be a git tag and specified like ''PKG_SOURCE_VERSION:=v$(PKG_VERSION)''.
  
 Buildroot will first clone the source repository, and then generate a tarball from the source repository, with a name like ''dl/odhcpd-2017-08-16-94e65ee0.tar.xz''. Buildroot will first clone the source repository, and then generate a tarball from the source repository, with a name like ''dl/odhcpd-2017-08-16-94e65ee0.tar.xz''.
Line 184: Line 187:
 :!: The tarballs generated from svn checkouts are not reproducible, so you should avoid defining ''PKG_MIRROR_HASH'' when building from svn! :!: The tarballs generated from svn checkouts are not reproducible, so you should avoid defining ''PKG_MIRROR_HASH'' when building from svn!
  
-To generate ''PKG_MIRROR_HASH'' automatically, use the following (replace ''package/network/services/odhcpd'' by your package):+To generate ''PKG_MIRROR_HASH'' automatically, use the following (replace ''package/odhcpd'' by your package):
  
 <code> <code>
 # First add "PKG_MIRROR_HASH:=skip" to the package Makefile and/or "HASH:=skip", if required. # First add "PKG_MIRROR_HASH:=skip" to the package Makefile and/or "HASH:=skip", if required.
-make package/network/services/odhcpd/download V=s +make package/odhcpd/download V=s 
-make package/network/services/odhcpd/check FIXUP=1 V=s+make package/odhcpd/check FIXUP=1 V=s
 </code> </code>
  
Line 202: Line 205:
 </code> </code>
  
-History: ''PKG_MIRROR_MD5SUM'' was [[https://git.lede-project.org/b568a64f8c1f7c077c83d8c189d4c84ca270aeb4|introduced in 2011]] and [[https://git.lede-project.org/7416d2e046b87b262b407f8af70b8dd9b2927c70|renamed to ''PKG_MIRROR_HASH'' in LEDE in 2016]].+History: ''PKG_MIRROR_MD5SUM'' was [[commit>?p=openwrt/openwrt.git;a=commitdiff;h=b568a64f8c1f7c077c83d8c189d4c84ca270aeb4|introduced in 2011]] and [[commit>?p=openwrt/openwrt.git;a=commitdiff;h=7416d2e046b87b262b407f8af70b8dd9b2927c70|renamed to ''PKG_MIRROR_HASH'' in 2016]].
  
  
Line 621: Line 624:
 :!: ** Don't use this anymore! ** :!: ** 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).+Support for this style of local source building was removed. 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: 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:
Line 634: Line 637:
 ===== Creating packages for kernel modules ===== ===== Creating packages for kernel modules =====
  
-A [[http://www.digitalhermit.com/linux/Kernel-Build-HOWTO.html|kernel module]] is an installable program which extends the behavior of the linux kernel. A kernel module gets loaded after the kernel itself, E.G. using ''insmod''.+A [[https://wiki.archlinux.org/title/Kernel_module|kernel module]] is an installable program which extends the behavior of the linux kernel. A kernel module gets loaded after the kernel itself, E.G. using ''insmod''.
  
 Many kernel programs are included in the Linux source distribution; typically the kernel build may be configured to, for each program,  Many kernel programs are included in the Linux source distribution; typically the kernel build may be configured to, for each program, 
Line 806: Line 809:
 $(eval $(call KernelPackage,madwifi)) $(eval $(call KernelPackage,madwifi))
 </code> </code>
 +---- 
 +=== The use of MODPARAMS ===
 If a module require some special param to be passed on Autoload, it's available MODPARAMS using the following syntax: If a module require some special param to be passed on Autoload, it's available MODPARAMS using the following syntax:
 <code>MODPARAMS.module_ko:=example_param1=example_value example_param2=example_value2</code> <code>MODPARAMS.module_ko:=example_param1=example_value example_param2=example_value2</code>
Line 821: Line 825:
  AUTOLOAD:=$(call AutoLoad,50,cryptodev)  AUTOLOAD:=$(call AutoLoad,50,cryptodev)
  MODPARAMS.cryptodev:=cryptodev_verbosity=-1  MODPARAMS.cryptodev:=cryptodev_verbosity=-1
 +endef
 +</code>
 +----
 +=== Make a Kernel Module required for boot ====
 +
 +Some modules may be required for the correct operation of the device. One example would be an ethernet driver required for the correct operation of the switch on the device.\\
 +
 +To flag a Kernel Module this way it's needed to append ''1'' to ''AUTOLOAD'' at the end.\\
 +
 +This cause the module file to get placed in /etc/modules-boot.d/ instead of /etc/modules.d/, modules-boot.d is processed by procd init before launching preinit and correctly works both in a normal boot and in a failsafe boot. All of this is with the assumption that the module is installed in the firmware and not with OPKG on a loaded system as **it needs to be present before /overlay is mounted**. (OPKG installed module are present only in after /overlay is mounted)
 +
 +For example here is ''phy-realtek'' in ''package/kernel/linux/modules/netdevices.mk'':
 +<code make>
 +define KernelPackage/phy-realtek
 +   SUBMENU:=$(NETWORK_DEVICES_MENU)
 +   TITLE:=Realtek Ethernet PHY driver
 +   KCONFIG:=CONFIG_REALTEK_PHY
 +   DEPENDS:=+kmod-libphy
 +   FILES:=$(LINUX_DIR)/drivers/net/phy/realtek.ko
 +   AUTOLOAD:=$(call AutoLoad,18,realtek,1)
 endef endef
 </code> </code>
Line 853: Line 877:
 Very basic example of a suitable init.d script. Please note that the newer style version does not work properly with interpreted executables (i.e. scripts). That is because start-stop-daemon is used by service_stop() in a way that it makes it confuse the script name with the interpreter name. Very basic example of a suitable init.d script. Please note that the newer style version does not work properly with interpreted executables (i.e. scripts). That is because start-stop-daemon is used by service_stop() in a way that it makes it confuse the script name with the interpreter name.
  
-:!: **procd** style init is used in some init.d scripts since: https://dev.openwrt.org/changeset/38023 . +:!: **procd** style init is used in some init.d scripts since [[commit>?p=openwrt/openwrt.git;a=commit;h=f87409440298121ae1fbd718a17267cc180438e4|this commit]]. 
-See [[docs:guide-developer:procd-init-scripts]] for more details on that+See [[docs:guide-developer:procd-init-scripts]] for more details on that.
  
 <code bash> <code bash>
Line 904: Line 928:
  
   * https://github.com/openwrt/packages   * https://github.com/openwrt/packages
-  * https://dev.openwrt.org/wiki/SubmittingPatches+  * [[:submitting-patches|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+See [[https://web.archive.org/web/20170629071358/https://lists.openwrt.org/pipermail/openwrt-devel/2014-June/025810.html|the original announcement]] of this change.
  • Last modified: 2022/01/04 09:18
  • by hardfalcon