docs/manual/customize-packages.txt

   1 // -*- mode:doc; -*-
   2 // vim: set syntax=asciidoc:
   3
   4 [[customize-packages]]
   5 === Adding project-specific packages
   6
   7 In general, any new package should be added directly in the +package+
   8 directory and submitted to the Buildroot upstream project. How to add
   9 packages to Buildroot in general is explained in full detail in
  10 xref:adding-packages[] and will not be repeated here. However, your
  11 project may need some proprietary packages that cannot be upstreamed.
  12 This section will explain how you can keep such project-specific
  13 packages in a project-specific directory.
  14
  15 As shown in xref:customize-dir-structure[], the recommended location for
  16 project-specific packages is +package/<company>/+. If you are using the
  17 +BR2_EXTERNAL+ feature (see xref:outside-br-custom[]) the recommended
  18 location is +$(BR2_EXTERNAL)/package/+.
  19
  20 However, Buildroot will not be aware of the packages in this location,
  21 unless we perform some additional steps. As explained in
  22 xref:adding-packages[], a package in Buildroot basically consists of two
  23 files: a +.mk+ file (describing how to build the package) and a
  24 +Config.in+ file (describing the configuration options for this
  25 package).
  26
  27 Buildroot will automatically include the +.mk+ files in first-level
  28 subdirectories of the +package+ directory (using the pattern
  29 +package/\*/*.mk+). If we want Buildroot to include +.mk+ files from
  30 deeper subdirectories (like +package/<company>/package1/+) then we
  31 simply have to add a +.mk+ file in a first-level subdirectory that
  32 includes these additional +.mk+ files. Therefore, create a file
  33 +package/<company>/<company>.mk+ with following contents (assuming you
  34 have only one extra directory level below +package/<company>/+):
  35
  36 -----
  37 include $(sort $(wildcard package/<company>/*/*.mk))
  38 -----
  39
  40 If you are using +BR2_EXTERNAL+, create a file
  41 +$(BR2_EXTERNAL)/external.mk+ with following contents (again assuming only
  42 one extra level):
  43
  44 -----
  45 include $(sort $(wildcard $(BR2_EXTERNAL)/package/*/*.mk))
  46 -----
  47
  48 For the +Config.in+ files, create a file +package/<company>/Config.in+
  49 that includes the +Config.in+ files of all your packages. An exhaustive
  50 list has to be provided since wildcards are not supported in the source command of kconfig.
  51 For example:
  52
  53 -----
  54 source "package/<company>/package1/Config.in"
  55 source "package/<company>/package2/Config.in"
  56 -----
  57
  58 Include this new file +package/<company>/Config.in+ from
  59 +package/Config.in+, preferably in a company-specific menu to make
  60 merges with future Buildroot versions easier.
  61
  62 If you are using +BR2_EXTERNAL+, create a file
  63 +$(BR2_EXTERNAL)/Config.in+ with similar contents:
  64
  65 -----
  66 source "$BR2_EXTERNAL/package/package1/Config.in"
  67 source "$BR2_EXTERNAL/package/package2/Config.in"
  68 -----
  69
  70 You do not have to add an include for this +$(BR2_EXTERNAL)/Config.in+
  71 file as it is included automatically.