Yocto - bb脚本中使用的SRC_URI、SRCREV和S

我们遇到的各种自己不了解的技术或产品时，都需要阅读用户手册。用户手册里的内容很多时，除了由目录组织文档结构外，通常还有有一个词汇表，一般作为附录放在文档最后。

通过这个按照字母排序的词汇表，可以在对整个文档还不够了解的情况下，快速的定位到自己需要的内容。

比如，我们打开Yocto的manual：Welcome to the Yocto Project Documentation — The Yocto Project ® 4.3.999 documentation

在左侧列表中找到“Reference Manual”，点开，在展开的列表中，继续选择“12 Variables Glossary”，上方点击首字母S，在下方页面中搜索到SRI_URI。

然后就可以得到关于SRI_URI的有用介绍：

See the BitBake manual for the initial description for this variable: SRC_URI.

有关该变量的初始描述，请参阅 BitBake 手册： SRC_URI。

所以，这个变量是用于BitBake的，它会识别和使用这个变量。你在bb脚本中设置这个变量，bitbake在构建时使用。

Bitbake关于此变量的说明的链接：

5 Variables Glossary — Bitbake dev documentation

SRC_URI

源文件列表 - 本地或远程。这个变量告诉 BitBake 在编译时要提取哪些文件，以及如何提取。例如，如果配方或附加文件需要从互联网上获取一个 tar 包，配方或附加文件就会使用 SRC_URI 条目指定该 tar 包。另一方面，如果配方或附加文件需要获取一个压缩包、应用两个补丁并包含一个自定义文件，则配方或附加文件需要一个 SRC_URI 变量来指定所有这些来源。

The list of source files — local or remote. This variable tells BitBake which bits to pull for the build and how to pull them. For example, if the recipe or append file needs to fetch a single tarball from the Internet, the recipe or append file uses a SRC_URI entry that specifies that tarball. On the other hand, if the recipe or append file needs to fetch a tarball, apply two patches, and include a custom file, the recipe or append file needs an SRC_URI variable that specifies all those sources.

下面的列表解释了可用的 URI 协议。URI 协议高度依赖于特定的 BitBake Fetcher 子模块。根据 BitBake 使用的撷取器，会使用不同的 URL 参数。有关所支持的提取器的详细信息，请参阅提取器部分。

The following list explains the available URI protocols. URI protocols are highly dependent on particular BitBake Fetcher submodules. Depending on the fetcher BitBake uses, various URL parameters are employed. For specifics on the supported Fetchers, see the Fetchers section.

* az://: Fetches files from an Azure Storage account using HTTPS.

* bzr://: Fetches files from a Bazaar revision control repository.

* ccrc://: Fetches files from a ClearCase repository.

* cvs://: Fetches files from a CVS revision control repository.

* file://: Fetches files, which are usually files shipped with the Metadata, from the local machine. The path is relative to the FILESPATH variable. Thus, the build system searches, in order, from the following directories, which are assumed to be a subdirectories of the directory in which the recipe file (.bb) or append file (.bbappend) resides:

    * ${BPN}: the base recipe name without any special suffix or version numbers.

    * ${BP} - ${BPN}-${PV}: the base recipe name and version but without any special package name suffix.

    * files: files within a directory, which is named files and is also alongside the recipe or append file.

* ftp://: Fetches files from the Internet using FTP.

* git://: Fetches files from a Git revision control repository.

* gitsm://: Fetches submodules from a Git revision control repository.

* hg://: Fetches files from a Mercurial (hg) revision control repository.

* http://: Fetches files from the Internet using HTTP.

* https://: Fetches files from the Internet using HTTPS.

* npm://: Fetches JavaScript modules from a registry.

* osc://: Fetches files from an OSC (OpenSUSE Build service) revision control repository.

* p4://: Fetches files from a Perforce (p4) revision control repository.

* repo://: Fetches files from a repo (Git) repository.

* ssh://: Fetches files from a secure shell.

* svn://: Fetches files from a Subversion (svn) revision control repository.

这里还有一些值得一提的选项：

Here are some additional options worth mentioning:

• downloadfilename：指定存储下载文件时使用的文件名。

• name：在 SRC_URI 中指定多个文件或 git 仓库时，用于识别与 SRC_URI 校验和或 SRCREV 关联的名称。例如

SRC_URI = "git://example.com/foo.git;branch=main;name=first \

           git://example.com/bar.git;branch=main;name=second \

           http://example.com/file.tar.gz;name=third"

SRCREV_first = "f1d2d2f924e986ac86fdf7b36c94bcdf32beec15"

SRCREV_second = "e242ed3bffccdf271b7fbaf34ed72d089537b42f"

SRC_URI[third.sha256sum] = "13550350a8681c84c861aac2e5b440161c2b33a3e4f302ac680ca5b686de48de"

• subdir： 将文件（或提取其内容）放入指定的子目录。该选项对于不常见的 tar 包或其他存档文件很有用，因为这些存档中的文件可能没预先放在一个子目录中。

• subpath： 在使用 Git fetcher 时，将checkout代码仓库的树状文件结构的一部分。如果不设置subpath，也可以在设置S变量时指定使用git代码仓库的某个子目录。

• unpack： 如果文件是存档格式，控制是否解压缩。默认操作是解压文件。=1是解压，=0是不解压。

SRCREV

12 Variables Glossary — The Yocto Project ® 4.3.999 documentation

用于构建软件包的源代码的修订版本。此变量仅适用于 Subversion、Git、Mercurial 和 Bazaar。如果你想构建一个固定的修订版本，又想避免每次 BitBake 解析你的配方时都在远程版本库中执行查询，你应该指定一个完整修订版本标识符的 SRCREV，而不仅仅是一个标签。

The revision of the source code used to build the package. This variable applies only when using Subversion, Git, Mercurial and Bazaar. If you want to build a fixed revision and you want to avoid performing a query on the remote repository every time BitBake parses your recipe, you should specify a SRCREV that is a full revision identifier and not just a tag.

S

12 Variables Glossary — The Yocto Project ® 4.3.999 documentation

已解压缩的配方要用的源代码，其所在构建目录中的位置。默认情况下，该目录为 ${WORKDIR}/${BPN}-${PV}，其中 ${BPN} 是基本配方名称，${PV} 是配方版本。如果源代码压缩包将代码提取到 ${BPN}-${PV} 以外的目录，或者源代码是从 Git 或 Subversion 等 SCM 获取的，则必须在配方中设置 S，以便 OpenEmbedded 构建系统知道在哪里可以找到已解压的源代码。

The location in the Build Directory where unpacked recipe source code resides. By default, this directory is ${WORKDIR}/${BPN}-${PV}, where ${BPN} is the base recipe name and ${PV} is the recipe version. If the source tarball extracts the code to a directory named anything other than ${BPN}-${PV}, or if the source code is fetched from an SCM such as Git or Subversion, then you must set S in the recipe so that the OpenEmbedded build system knows where to find the unpacked source.

举例来说，假设源代码目录的顶级文件夹名为 poky，默认的编译目录为 poky/build。在这种情况下，构建系统用来保存名为db的配方的解压文件的工作目录如下：

As an example, assume a Source Directory top-level folder named poky and a default Build Directory at poky/build. In this case, the work directory the build system uses to keep the unpacked recipe for db is the following:

poky/build/tmp/work/qemux86-poky-linux/db/5.1.19-r3/db-5.1.19

解压后的源代码位于 db-5.1.19 文件夹中。

下一个示例假设有一个 Git 仓库。默认情况下，Git 仓库会在 do_fetch 过程中克隆到 ${WORKDIR}/git。由于该路径与默认值 S 不同，因此必须特别设置，以便找到源代码：

The unpacked source code resides in the db-5.1.19 folder.

This next example assumes a Git repository. By default, Git repositories are cloned to ${WORKDIR}/git during do_fetch. Since this path is different from the default value of S, you must set it specifically so the source can be located:

SRC_URI = "git://path/to/repo.git;branch=main"

S = "${WORKDIR}/git"

FETCHERS

4 File Download Support — Bitbake dev documentation

4.3 Fetchers

如前所述，URL 前缀决定了 BitBake 使用哪个提取子模块。每个子模块可以支持不同的 URL 参数，下面将对此进行介绍。

As mentioned earlier, the URL prefix determines which fetcher submodule BitBake uses. Each submodule can support different URL parameters, which are described in the following sections.

4.3.1 Local file fetcher (file://)   #本地文件提取器

该子模块处理以 file:// 开头的 URL。在 URL 中指定的文件名可以是文件的绝对路径，也可以是相对路径。如果文件名是相对路径，则使用 FILESPATH 变量的内容，与 PATH 用于查找可执行文件的方式相同。如果找不到文件，则假定在调用download()方法时，文件在 DL_DIR 中可用。

This submodule handles URLs that begin with file://. The filename you specify within the URL can be either an absolute or relative path to a file. If the filename is relative, the contents of the FILESPATH variable is used in the same way PATH is used to find executables. If the file cannot be found, it is assumed that it is available in DL_DIR by the time the download() method is called.

如果指定一个目录，则整个目录都会被解压缩。

下面是几个 URL 示例，第一个是相对 URL，第二个是绝对 URL：

If you specify a directory, the entire directory is unpacked.

Here are a couple of example URLs, the first relative and the second absolute:

SRC_URI = "file://relativefile.patch"

SRC_URI = "file:///Users/ich/very_important_software"

4.3.5 Git Fetcher (git://)   #Git仓库提取器

这个提取子模块从 Git 源代码控制系统中取回代码。提取器的工作原理是在 GITDIR（通常是 DL_DIR/git2）中创建一个远程的裸克隆。然后从裸克隆中再clone到工作目录，也就是checkout一个特定的tree，解压到工作目录。这样做是为了尽量减少磁盘上的重复数据量，并使解包过程更快。使用的可执行文件可通过 FETCHCMD_git 设置。

This fetcher submodule fetches code from the Git source control system. The fetcher works by creating a bare clone of the remote into GITDIR, which is usually DL_DIR/git2. This bare clone is then cloned into the work directory during the unpack stage when a specific tree is checked out. This is done using alternates and by reference to minimize the amount of duplicate data on the disk and make the unpack process fast. The executable used can be set with FETCHCMD_git.

此提取器支持的参数如下：

• “protocol”: The protocol used to fetch the files. The default is “git” when a hostname is set. If a hostname is not set, the Git protocol is “file”. You can also use “http”, “https”, “ssh” and “rsync”.

• “nocheckout”: Tells the fetcher to not checkout source code when unpacking when set to “1”. Set this option for the URL where there is a custom routine to checkout code. The default is “0”.

• “rebaseable”: Indicates that the upstream Git repository can be rebased. You should set this parameter to “1” if revisions can become detached from branches. In this case, the source mirror tarball is done per revision, which has a loss of efficiency. Rebasing the upstream Git repository could cause the current revision to disappear from the upstream repository. This option reminds the fetcher to preserve the local cache carefully for future use. The default value for this parameter is “0”.

• “nobranch”: Tells the fetcher to not check the SHA validation for the branch when set to “1”. The default is “0”. Set this option for the recipe that refers to the commit that is valid for any namespace (branch, tag, …) instead of the branch.

• “bareclone”: Tells the fetcher to clone a bare clone into the destination directory without checking out a working tree. Only the raw Git metadata is provided. This parameter implies the “nocheckout” parameter as well.

• “branch”: The branch(es) of the Git tree to clone. Unless “nobranch” is set to “1”, this is a mandatory parameter. The number of branch parameters must match the number of name parameters.

• “rev”: The revision to use for the checkout. The default is “master”.

• “tag”: Specifies a tag to use for the checkout. To correctly resolve tags, BitBake must access the network. For that reason, tags are often not used. As far as Git is concerned, the “tag” parameter behaves effectively the same as the “rev” parameter.

• “subpath”: Limits the checkout to a specific subpath of the tree. By default, the whole tree is checked out.

• “destsuffix”: The name of the path in which to place the checkout. By default, the path is git/.

• “usehead”: Enables local git:// URLs to use the current branch HEAD as the revision for use with AUTOREV. The “usehead” parameter implies no branch and only works when the transfer protocol is file://.

注意：

在使用protocol参数时，当协议为 "ssh "时，SRC_URI中的预期URL 与通常传递给 git clone 命令的不同，后者是由 Git 服务器提供的URL来提取内容的。例如，通过 SSH 克隆时，GitLab 服务器返回的 mesa 的 URL 是 [e-mail]:mesa/mesa.git，但 SRC_URI 中的预期 URL 却如下：

SRC_URI = "git://[e-mail]/mesa/mesa.git;branch=main;protocol=ssh;..."

注意项目路径前的:字符改为/。

一些URL的例子如下：

SRC_URI = "git://github.com/fronteed/icheck.git;protocol=https;branch=${PV};tag=${PV}"

SRC_URI = "git://github.com/asciidoc/asciidoc-py;protocol=https;branch=main"

SRC_URI = "git://[e-mail]/mesa/mesa.git;branch=main;protocol=ssh;..."

当使用 git 作为软件主源代码的获取器时，应相应地设置 S：

S = "${WORKDIR}/git"

注意：

不支持在 git:// urls 中直接指定密码。原因有几个： SRC_URI 通常会被写入日志或其他地方，这很容易泄露密码；而且不删除密码的话，会导致元数据共享太容易。可以使用 SSH 密钥、~/.netrc 和 ~/.ssh/config 文件作为替代。

在 git fetcher 中使用标签可能会导致令人惊讶的行为。Bitbake 需要将标签解析到特定版本，为此必须连接并使用上游版本库(upstream repository)。这是因为标签(tag)指向的版本(revision)可能会发生变化，我们曾在著名的公共软件源中看到过这种情况。这可能意味着网络连接比预期的要多得多，而且每次构建时都要重新解析配方。源镜像(Source mirrors)也会被绕过，因为上游版本库是准确解析版本的唯一真实来源。出于这些原因，虽然提取器可以支持标签，但我们还是建议在配方中具体指定修订版本。

联合起来使用

通过上面的介绍，在bb文件中通过这些变量来获取需要构建的目标文件的源代码。

比如，项目里通常会使用git协议来获取源代码。而在本地调试时，可以修改称本地路径。

第一种：

SRC_URI = "git://[e-mail]:7999/platform/projectname.git;protocol=ssh;nobranch=1"

SRCREV = "c3f56703e58af33dbf808f903de694bcde3269cd"

S = "${WORKDIR}/git"

第二种：

SRC_URI = "file://${TOPDIR}/../../projectname"

S = "${WORKDIR}/${TOPDIR}/../../projectname"

这里用到了${TOPDIR}。

(结束)