| Both sides previous revision Previous revision Next revision | Previous revision |
| docs:guide-developer:feeds [2018/12/15 18:50] – [Feed Configuration] jeff | docs:guide-developer:feeds [2021/10/15 09:06] (current) – ↷ Links adapted because of a move operation bobafetthotmail |
|---|
| In OpenWrt, a "feed" is a collection of [[docs:guide-developer:packages]] which share a common location. Feeds may reside on a remote server, in a version control system, on the local filesystem, or in any other location addressable by a single name (path/URL) over a protocol with a supported feed method. | In OpenWrt, a "feed" is a collection of [[docs:guide-developer:packages]] which share a common location. Feeds may reside on a remote server, in a version control system, on the local filesystem, or in any other location addressable by a single name (path/URL) over a protocol with a supported feed method. |
| |
| Feeds are additional predefined package build recipes for OpenWrt Buildroot. | Feeds are additional predefined package build recipes for OpenWrt Buildroot. They may be configured to support custom feeds or non-default feed packages via a feed configuration file. |
| | |
| | ===== Feed Configuration ===== |
| | |
| | The list of usable feeds is configured from either the ''feeds.conf'' file, if it exists, or otherwise the ''feeds.conf.default'' file. This file contains a list of feeds with each feed listed on a separate line. Each feed line consists of 3 whitespace-separated components: The feed method, the feed name, and the feed source. Blank lines, excessive white-space/newlines, and comments are ignored during parsing. Comments begin with `#` and extend to the end of a line. |
| | |
| | |
| | As of 2018-12-15 on the ''master'' branch, the defaults contained within ''feeds.conf.default'' appear as follows. Note that the ''#'' prefixed lines are commented out and included for ease of configuration. |
| | <file xml feeds.conf.default> |
| | src-git packages https://git.openwrt.org/feed/packages.git |
| | src-git luci https://git.openwrt.org/project/luci.git |
| | src-git routing https://git.openwrt.org/feed/routing.git |
| | src-git telephony https://git.openwrt.org/feed/telephony.git |
| | #src-git video https://github.com/openwrt/video.git |
| | #src-git targets https://github.com/openwrt/targets.git |
| | #src-git management https://github.com/openwrt-management/packages.git |
| | #src-git oldpackages http://git.openwrt.org/packages.git |
| | #src-link custom /usr/src/openwrt/custom-feed |
| | </file> |
| | |
| | The git method can specify a specific branch or commit using the following formats |
| | <file> |
| | src-git local_feed_name https://example.com/repo_name/something.git;branch_name |
| | src-git local_feed_name https://example.com/repo_name/something.git^commit_hash |
| | </file> |
| | |
| | As of this writing, the following feed methods are supported: |
| | |
| | ^ Method ^ Function ^ |
| | | src-bzr | Data is downloaded from the source path/URL using ''bzr'' | |
| | | src-cpy | Data is copied from the source path. The path can be specified as either relative to OpenWrt repository root or absolute. | |
| | | src-darcs | Data is downloaded from the source path/URL using ''darcs'' | |
| | | src-git | Data is downloaded from the source path/URL using ''git'' as a shallow (depth of 1) clone | |
| | | src-git-full | Data is downloaded from the source path/URL using ''git'' as a full clone | |
| | | src-gitsvn | Bidirectional operation between a Subversion repository and git | |
| | | src-hg | Data is downloaded from the source path/URL using ''hg'' | |
| | | src-link | A symlink to the source path is created. The path must be absolute. | |
| | | src-svn | Data is downloaded from the source path/URL using ''svn'' | |
| | |
| | Feed names are used to identify feeds and serve as the basis for several file and directory names that are created to hold information about the feeds. The feed source is the location from which the feed data is downloaded. |
| | |
| | For the methods listed above which rely on version control systems that support a "limited history" option (such as ''%%--%%depth=1'' for git and ''%%--%%lightweight'' for bzr) the smallest available history is downloaded. This is a good default, but developers who are actively committing to a feed and/or using the commit history may want to change this behavior. This can be done by editing ''scripts/feeds'' to use ''src-git-full'' or by checking out the feed without using ''scripts/feeds''. A shallow git clone can be updated to a "full" clone through use of ''git fetch %%--%%unshallow'' |
| |
| ===== Working with Feeds ===== | ===== Working with Feeds ===== |
| |
| Feeds are retrieved and managed by ''scripts/feeds'', a perl script as of December, 2018. | As of December, 2018, feeds are retrieved and managed by the script ''scripts/feeds'' within the ''openwrt/openwrt.git'' repository. The ''feeds'' script incorporates packages from a variety of feed sources into the OpenWrt build system. This is a two step process done by the developer before building an image by updating a feed followed by installing packages from specific to that feed. |
| |
| The ''feeds'' script reads the configured feeds, obtains the current or specified version of each of them, and "installs" them. | During the ''update'' step, the feeds are obtained from their sources listed within a [[docs:guide-developer:feeds#feed_configuration|feed configuration]] and then copied into the ''feeds'' directory. After a successful update, each package recipe within a feed is represented within a folder in ''feeds/<feed_name>/<package_name>/'', but they are not currently incorporated into the OpenWrt build system as they are not contained within the `package/` directory. |
| |
| FIXME: Just what does "install" mean? | During the ''install'' step, packages from the feeds obtained during an `update` are then linked into the ''package/feeds/<feed_name>'' folder, where ''<feed_name>'' is replaced by the name of the feed in the feed configuration. After this step, it is then possible to perform package specific make operations by utilizing their path within the ''package/'' folder. For example: |
| |
| FIXME: How to create your own "feed" of your own packages | ''make package/feeds/<feed_name>/<package_name>'' |
| |
| <file> | <file> |
| </file> | </file> |
| |
| |
| ==== Feed Configuration ==== | |
| |
| The list of usable feeds is configured from the ''feeds.conf'' file (or | |
| ''feeds.conf.default'' when ''feeds.conf'' does not exist). This file contains a list of feeds, one per line, and any number of empty lines. ''feeds.conf'' is used //instead of// ''feeds.conf.default'' if the former exists, not in //addition to,// so users wishing to //add// feeds may wish to copy the contents of ''feeds.conf.default'' to ''feeds.conf''. | |
| |
| Comments begin with # and extend to the end of a line and are ignored during parsing. Each feed line consists of 3 whitespace-separated components: The feed method, the feed name, and the feed source. | |
| |
| As of 2018-12-15 the file ''feeds.conf.default'' contains, on the ''master'' branch: | |
| <file xml feeds.conf.default> | |
| src-git packages https://git.openwrt.org/feed/packages.git | |
| src-git luci https://git.openwrt.org/project/luci.git | |
| src-git routing https://git.openwrt.org/feed/routing.git | |
| src-git telephony https://git.openwrt.org/feed/telephony.git | |
| #src-git video https://github.com/openwrt/video.git | |
| #src-git targets https://github.com/openwrt/targets.git | |
| #src-git management https://github.com/openwrt-management/packages.git | |
| #src-git oldpackages http://git.openwrt.org/packages.git | |
| #src-link custom /usr/src/openwrt/custom-feed | |
| </file> | |
| |
| The git method can specify a specific branch or commit using the following formats | |
| <file> | |
| src-git local_feed_name https://example.com/repo_name/something.git;branch_name | |
| src-git local_feed_name https://example.com/repo_name/something.git^commit_hash | |
| </file> | |
| |
| As of this writing, the following methods are supported: | |
| |
| ^ Method ^ Function ^ | |
| | src-bzr | Data is downloaded from the source path/URL using ''bzr'' | | |
| | src-cpy | Data is copied from the source path | | |
| | src-darcs | Data is downloaded from the source path/URL using ''darcs'' | | |
| | src-git | Data is downloaded from the source path/URL using ''git'' as a shallow (depth of 1) clone | | |
| | src-git-full | Data is downloaded from the source path/URL using ''git'' as a full clone | | |
| | src-gitsvn | Bidirectional operation between a Subversion repository and git | | |
| | src-hg | Data is downloaded from the source path/URL using ''hg'' | | |
| | src-link | A symlink to the source path is created | | |
| | src-svn | Data is downloaded from the source path/URL using ''svn'' | | |
| |
| Feed names are used to identify feeds and serve as the basis for several file and directory names that are created to hold information about the feeds. The feed source is the location from which the feed data is downloaded. | |
| |
| For the methods listed above which rely on version control systems that support a "limited history" option (such as ''%%--%%depth=1'' for git and ''%%--%%lightweight'' for bzr) the smallest available history is downloaded. This is a good default, but developers who are actively committing to a feed and/or using the commit history may want to change this behavior. This can be done by editing ''scripts/feeds'' to use ''src-git-full'' or by checking out the feed without using ''scripts/feeds''. A shallow git clone can be updated to a "full" clone through use of ''git fetch %%--%%unshallow'' | |
| |
| ==== Feed Commands ==== | ==== Feed Commands ==== |
| |
| === Install === | === Install === |
| The install command installs the applicable packages and any packages on which the applicable packages depend (both direct dependencies and build dependencies). The installation process consists of creating a symbolic link from ''packages/feeds/$feed_name/$package_name'' to ''feeds/$feed_name/$package_name'' so that the package will be included in the configuration process when the directory hierarchy under ''packages'' is searched. | |
| | The install command installs the applicable packages and any packages on which the applicable packages depend (both direct dependencies and build dependencies). The installation process consists of creating a symbolic link from ''package/feeds/$feed_name/$package_name'' to ''feeds/$feed_name/$package_name'' so that the package will be included in the configuration process when the directory hierarchy under ''packages'' is searched. |
| |
| ^ Command ^ Description ^ | ^ Command ^ Description ^ |
| | ./scripts/feeds install -a | Install all packages (not recommended, only install the packages you need) | | | ./scripts/feeds install -a | Install all packages (not required; packages can be installed on an as-needed basis for slow build machines) | |
| | ./scripts/feeds install luci | Install only the package LuCI | | | ./scripts/feeds install luci | Install only the package LuCI | |
| | ./scripts/feeds install -a -p luci | Install the complete LuCI WebUI by installing all (-a) packages from the preferred feed (-p) luci | | | ./scripts/feeds install -a -p luci | Install the complete LuCI WebUI by installing all (-a) packages from the preferred feed (-p) luci | |
| === Uninstall === | === Uninstall === |
| |
| The uninstall command does the opposite of the install command (although it does not address dependent packages in any way). It simply removes any symlinks to the package from the subdirectories of ''packages/feeds''. | The uninstall command does the opposite of the install command (although it does not address dependent packages in any way). It simply removes any symlinks to the package from the subdirectories of ''package/feeds''. |
| |
| === Update === | === Update === |
| |
| ==== Creating the package directory ==== | ==== Creating the package directory ==== |
| | |
| | For this example we assume that your are in ''/home/user/openwrt'' as your base directory. |
| |
| === Adding your package to an existing feed === | === Adding your package to an existing feed === |
| |
| For this example we assume that your are in ''/home/user/openwrt'' as your base directory. | |
| |
| - You create your current project dir ''project''. | FIXME |
| - Then while in ''/home/user/openwrt/project'' | |
| - ''svn co svn://svn.openwrt.org/openwrt/trunk openwrt'' (for the OpenWRT base system) | |
| - ''svn co svn://svn.openwrt.org/openwrt/packages packages'' (for the packages feed) | |
| - Add your package in the appropriate subdirectory under ''/home/user/openwrt/project/packages'' | |
| |
| === Creating your own feed === | === Adding your package to your own feed === |
| - Create your project dir and get trunk, as above | |
| - Create your package dir and copy your package into it (e.g. ''cp packagedir /home/user/openwrt/project/customfeed/''), so that your package is under (in this example) ''/home/user/openwrt/project/customfeed/packagedir'' | |
| |
| ==== Using the feed ==== | For this example we assume that you name your feed ''custom'' and your project is called ''helloworld'' and its openwrt Makefile is located at ''/usr/src/openwrt/custom-feed/helloworld/Makefile''. |
| - Edit your ''feeds.conf'' (i.e. ''/home/user/openwrt/project/openwrt/feeds.conf'') | |
| - Add a new line to access the feed (and in the case of adding to the packages feed comment out the normal packages feed.) | |
| - e.g. | |
| |
| | ''#srv-svn packages %%svn://svn.openwrt.org/openwrt/packages%% | - Edit ''/home/user/openwrt/feeds.conf.default'' |
| src-link customfeed /home/user/openwrt/project/packages'' | | - Add a new line for your feed. <code>src-link custom /usr/src/openwrt/custom-feed/</code> |
| |
| or in the case of the second example: | |
| |
| | ''src-link customfeed /home/user/openwrt/project/customfeed'' | | - Update the feed: from the ''<buildroot dir>'' (e.g. ''/home/user/openwrt'') do: <code>./scripts/feeds update custom</code> |
| | - And then install it <code>./scripts/feeds install -a -p custom</code> |
| |
| - Update the feed: from the ''<buildroot dir>'' (e.g. ''/home/user/openwrt/project/openwrt'') do: <code>./scripts/feeds update customfeed</code> | |
| - And then install it <code>./scripts/feeds install -p customfeed</code> | ==== Using the feed ==== |
| - Now your package(s) should be available when you do <code>make menuconfig</code> | - Now your package(s) should be available when you do <code>make menuconfig</code> |
| |
| |
| ==== Documentation ==== | ==== Documentation ==== |
| - [[docs:guide-developer:build-system:start|OpenWrt Buildroot – About]] | - [[docs:guide-developer:toolchain:start|OpenWrt Buildroot – About]] |
| - [[docs:guide-developer:build-system:install-buildsystem|OpenWrt Buildroot – Installation]] | - [[docs:guide-developer:toolchain:install-buildsystem|OpenWrt Buildroot – Installation]] |
| - [[docs:guide-developer:build-system:use-buildsystem|OpenWrt Buildroot – Usage]] | - [[docs:guide-developer:toolchain:use-buildsystem|OpenWrt Buildroot – Usage]] |
| - OpenWrt Buildroot – Feeds | - OpenWrt Buildroot – Feeds |
| - [[docs:techref:buildroot|OpenWrt Buildroot – Technical Reference]] {{:meta:icons:tango:48px-construction.svg.png?nolink&16}} this article needs //your// attention. | - [[docs:techref:buildroot|OpenWrt Buildroot – Technical Reference]] {{:meta:icons:tango:48px-construction.svg.png?nolink&16}} this article needs //your// attention. |