adding-packages-virtual.txt 4.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144
  1. // -*- mode:doc; -*-
  2. // vim: set syntax=asciidoc:
  3. === Infrastructure for virtual packages
  4. [[virtual-package-tutorial]]
  5. In Buildroot, a virtual package is a package whose functionalities are
  6. provided by one or more packages, referred to as 'providers'. The virtual
  7. package management is an extensible mechanism allowing the user to choose
  8. the provider used in the rootfs.
  9. For example, 'OpenGL ES' is an API for 2D and 3D graphics on embedded systems.
  10. The implementation of this API is different for the 'Allwinner Tech Sunxi' and
  11. the 'Texas Instruments OMAP35xx' platforms. So +libgles+ will be a virtual
  12. package and +sunxi-mali+ and +ti-gfx+ will be the providers.
  13. ==== +virtual-package+ tutorial
  14. In the following example, we will explain how to add a new virtual package
  15. ('something-virtual') and a provider for it ('some-provider').
  16. First, let's create the virtual package.
  17. ==== Virtual package's +Config.in+ file
  18. The +Config.in+ file of virtual package 'something-virtual' should contain:
  19. ---------------------------
  20. 01: config BR2_PACKAGE_HAS_SOMETHING_VIRTUAL
  21. 02: bool
  22. 03:
  23. 04: config BR2_PACKAGE_PROVIDES_SOMETHING_VIRTUAL
  24. 05: depends on BR2_PACKAGE_HAS_SOMETHING_VIRTUAL
  25. 06: string
  26. ---------------------------
  27. In this file, we declare two options, +BR2_PACKAGE_HAS_SOMETHING_VIRTUAL+ and
  28. +BR2_PACKAGE_PROVIDES_SOMETHING_VIRTUAL+, whose values will be used by the
  29. providers.
  30. ==== Virtual package's +.mk+ file
  31. The +.mk+ for the virtual package should just evaluate the +virtual-package+ macro:
  32. ---------------------------
  33. 01: ################################################################################
  34. 02: #
  35. 03: # something-virtual
  36. 04: #
  37. 05: ################################################################################
  38. 06:
  39. 07: $(eval $(virtual-package))
  40. ---------------------------
  41. The ability to have target and host packages is also available, with the
  42. +host-virtual-package+ macro.
  43. ==== Provider's +Config.in+ file
  44. When adding a package as a provider, only the +Config.in+ file requires some
  45. modifications.
  46. The +Config.in+ file of the package 'some-provider', which provides the
  47. functionalities of 'something-virtual', should contain:
  48. ---------------------------
  49. 01: config BR2_PACKAGE_SOME_PROVIDER
  50. 02: bool "some-provider"
  51. 03: select BR2_PACKAGE_HAS_SOMETHING_VIRTUAL
  52. 04: help
  53. 05: This is a comment that explains what some-provider is.
  54. 06:
  55. 07: http://foosoftware.org/some-provider/
  56. 08:
  57. 09: if BR2_PACKAGE_SOME_PROVIDER
  58. 10: config BR2_PACKAGE_PROVIDES_SOMETHING_VIRTUAL
  59. 11: default "some-provider"
  60. 12: endif
  61. ---------------------------
  62. On line 3, we select +BR2_PACKAGE_HAS_SOMETHING_VIRTUAL+, and on line 11, we
  63. set the value of +BR2_PACKAGE_PROVIDES_SOMETHING_VIRTUAL+ to the name of the
  64. provider, but only if it is selected.
  65. ==== Provider's +.mk+ file
  66. The +.mk+ file should also declare an additional variable
  67. +SOME_PROVIDER_PROVIDES+ to contain the names of all the virtual
  68. packages it is an implementation of:
  69. ---------------------------
  70. 01: SOME_PROVIDER_PROVIDES = something-virtual
  71. ---------------------------
  72. Of course, do not forget to add the proper build and runtime dependencies for
  73. this package!
  74. ==== Notes on depending on a virtual package
  75. When adding a package that requires a certain +FEATURE+ provided by a virtual
  76. package, you have to use +depends on BR2_PACKAGE_HAS_FEATURE+, like so:
  77. ---------------------------
  78. config BR2_PACKAGE_HAS_FEATURE
  79. bool
  80. config BR2_PACKAGE_FOO
  81. bool "foo"
  82. depends on BR2_PACKAGE_HAS_FEATURE
  83. ---------------------------
  84. ==== Notes on depending on a specific provider
  85. If your package really requires a specific provider, then you'll have to
  86. make your package +depends on+ this provider; you can _not_ +select+ a
  87. provider.
  88. Let's take an example with two providers for a +FEATURE+:
  89. ---------------------------
  90. config BR2_PACKAGE_HAS_FEATURE
  91. bool
  92. config BR2_PACKAGE_FOO
  93. bool "foo"
  94. select BR2_PACKAGE_HAS_FEATURE
  95. config BR2_PACKAGE_BAR
  96. bool "bar"
  97. select BR2_PACKAGE_HAS_FEATURE
  98. ---------------------------
  99. And you are adding a package that needs +FEATURE+ as provided by +foo+,
  100. but not as provided by +bar+.
  101. If you were to use +select BR2_PACKAGE_FOO+, then the user would still
  102. be able to select +BR2_PACKAGE_BAR+ in the menuconfig. This would create
  103. a configuration inconsistency, whereby two providers of the same +FEATURE+
  104. would be enabled at once, one explicitly set by the user, the other
  105. implicitly by your +select+.
  106. Instead, you have to use +depends on BR2_PACKAGE_FOO+, which avoids any
  107. implicit configuration inconsistency.