diff options
Diffstat (limited to 'poky/bitbake/doc')
5 files changed, 129 insertions, 77 deletions
diff --git a/poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-execution.rst b/poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-execution.rst index a4b1efbe8b..7b37f6615a 100644 --- a/poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-execution.rst +++ b/poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-execution.rst @@ -435,7 +435,7 @@ BitBake writes a shell script to executes the script. The generated shell script contains all the exported variables, and the shell functions with all variables expanded. Output from the shell script goes to the file -``${T}/log.do_taskname.pid``. Looking at the expanded shell functions in +``${``\ :term:`T`\ ``}/log.do_taskname.pid``. Looking at the expanded shell functions in the run file and the output in the log files is a useful debugging technique. diff --git a/poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst b/poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst index 4396830a2f..77384cfdc7 100644 --- a/poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst +++ b/poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst @@ -84,18 +84,18 @@ fetcher does know how to use HTTP as a transport. Here are some examples that show commonly used mirror definitions:: PREMIRRORS ?= "\ - bzr://.*/.\* http://somemirror.org/sources/ \\n \ - cvs://.*/.\* http://somemirror.org/sources/ \\n \ - git://.*/.\* http://somemirror.org/sources/ \\n \ - hg://.*/.\* http://somemirror.org/sources/ \\n \ - osc://.*/.\* http://somemirror.org/sources/ \\n \ - p4://.*/.\* http://somemirror.org/sources/ \\n \ - svn://.*/.\* http://somemirror.org/sources/ \\n" + bzr://.*/.\* http://somemirror.org/sources/ \ + cvs://.*/.\* http://somemirror.org/sources/ \ + git://.*/.\* http://somemirror.org/sources/ \ + hg://.*/.\* http://somemirror.org/sources/ \ + osc://.*/.\* http://somemirror.org/sources/ \ + p4://.*/.\* http://somemirror.org/sources/ \ + svn://.*/.\* http://somemirror.org/sources/" MIRRORS =+ "\ - ftp://.*/.\* http://somemirror.org/sources/ \\n \ - http://.*/.\* http://somemirror.org/sources/ \\n \ - https://.*/.\* http://somemirror.org/sources/ \\n" + ftp://.*/.\* http://somemirror.org/sources/ \ + http://.*/.\* http://somemirror.org/sources/ \ + https://.*/.\* http://somemirror.org/sources/" It is useful to note that BitBake supports cross-URLs. It is possible to mirror a Git repository on an @@ -167,6 +167,9 @@ govern the behavior of the unpack stage: - *dos:* Applies to ``.zip`` and ``.jar`` files and specifies whether to use DOS line ending conversion on text files. +- *striplevel:* Strip specified number of leading components (levels) + from file names on extraction + - *subdir:* Unpacks the specific URL to the specified subdirectory within the root directory. @@ -226,6 +229,11 @@ downloaded file is useful for avoiding collisions in :term:`DL_DIR` when dealing with multiple files that have the same name. +If a username and password are specified in the ``SRC_URI``, a Basic +Authorization header will be added to each request, including across redirects. +To instead limit the Authorization header to the first request, add +"redirectauth=0" to the list of parameters. + Some example URLs are as follows:: SRC_URI = "http://oe.handhelds.org/not_there.aac" @@ -388,6 +396,19 @@ This fetcher supports the following parameters: protocol is "file". You can also use "http", "https", "ssh" and "rsync". + .. note:: + + When ``protocol`` is "ssh", the URL expected in :term:`SRC_URI` differs + from the one that is typically passed to ``git clone`` command and provided + by the Git server to fetch from. For example, the URL returned by GitLab + server for ``mesa`` when cloning over SSH is + ``git@gitlab.freedesktop.org:mesa/mesa.git``, however the expected URL in + :term:`SRC_URI` is the following:: + + SRC_URI = "git://git@gitlab.freedesktop.org/mesa/mesa.git;protocol=ssh;..." + + Note the ``:`` character changed for a ``/`` before the path to the project. + - *"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". @@ -438,6 +459,7 @@ Here are some example URLs:: SRC_URI = "git://git.oe.handhelds.org/git/vip.git;tag=version-1" SRC_URI = "git://git.oe.handhelds.org/git/vip.git;protocol=http" + SRC_URI = "git://git@gitlab.freedesktop.org/mesa/mesa.git;protocol=ssh;..." .. note:: diff --git a/poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-intro.rst b/poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-intro.rst index 42263cef3a..1c31c1f9e8 100644 --- a/poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-intro.rst +++ b/poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-intro.rst @@ -537,7 +537,7 @@ current working directory: - ``pn-buildlist``: Shows a simple list of targets that are to be built. -To stop depending on common depends, use the "-I" depend option and +To stop depending on common depends, use the ``-I`` depend option and BitBake omits them from the graph. Leaving this information out can produce more readable graphs. This way, you can remove from the graph :term:`DEPENDS` from inherited classes such as ``base.bbclass``. diff --git a/poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst b/poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst index 119720d527..8496e1da53 100644 --- a/poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst +++ b/poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.rst @@ -104,15 +104,15 @@ Line Joining Outside of :ref:`functions <bitbake-user-manual/bitbake-user-manual-metadata:functions>`, BitBake joins any line ending in -a backslash character ("\") with the following line before parsing -statements. The most common use for the "\" character is to split +a backslash character ("\\") with the following line before parsing +statements. The most common use for the "\\" character is to split variable assignments over multiple lines, as in the following example:: FOO = "bar \ baz \ qaz" -Both the "\" character and the newline +Both the "\\" character and the newline character that follow it are removed when joining lines. Thus, no newline characters end up in the value of ``FOO``. @@ -125,7 +125,7 @@ Consider this additional example where the two assignments both assign .. note:: - BitBake does not interpret escape sequences like "\n" in variable + BitBake does not interpret escape sequences like "\\n" in variable values. For these to have an effect, the value must be passed to some utility that interprets escape sequences, such as ``printf`` or ``echo -n``. @@ -159,7 +159,7 @@ behavior:: C = "qux" *At this point, ${A} equals "qux bar baz"* B = "norf" - *At this point, ${A} equals "norf baz"\* + *At this point, ${A} equals "norf baz"* Contrast this behavior with the :ref:`bitbake-user-manual/bitbake-user-manual-metadata:immediate variable @@ -894,7 +894,7 @@ Regardless of the type of function, you can only define them in class Shell Functions --------------- -Functions written in shell script and executed either directly as +Functions written in shell script are executed either directly as functions, tasks, or both. They can also be called by other shell functions. Here is an example shell function definition:: @@ -944,7 +944,7 @@ Running ``do_foo`` prints the following:: Overrides and override-style operators can be applied to any shell function, not just :ref:`tasks <bitbake-user-manual/bitbake-user-manual-metadata:tasks>`. -You can use the ``bitbake -e`` recipename command to view the final +You can use the ``bitbake -e recipename`` command to view the final assembled function after all overrides have been applied. BitBake-Style Python Functions @@ -996,7 +996,7 @@ Running ``do_foo`` prints the following:: recipename do_foo: second recipename do_foo: third -You can use the ``bitbake -e`` recipename command to view +You can use the ``bitbake -e recipename`` command to view the final assembled function after all overrides have been applied. Python Functions @@ -1921,12 +1921,6 @@ The following list describes related variables: Specifies a function BitBake calls that determines whether BitBake requires a setscene dependency to be met. -- :term:`BB_STAMP_POLICY`: Defines the mode - for comparing timestamps of stamp files. - -- :term:`BB_STAMP_WHITELIST`: Lists stamp - files that are looked at when the stamp policy is "whitelist". - - :term:`BB_TASKHASH`: Within an executing task, this variable holds the hash of the task as returned by the currently enabled signature generator. diff --git a/poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst b/poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst index e955beb130..1bb55fc501 100644 --- a/poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst +++ b/poky/bitbake/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst @@ -374,12 +374,35 @@ overview of their function and contents. Specifies the Hash Equivalence server to use. If set to ``auto``, BitBake automatically starts its own server - over a UNIX domain socket. + over a UNIX domain socket. An option is to connect this server + to an upstream one, by setting :term:`BB_HASHSERVE_UPSTREAM`. - If set to ``host:port``, BitBake will use a remote server on the + If set to ``unix://path``, BitBake will connect to an existing + hash server available over a UNIX domain socket. + + If set to ``host:port``, BitBake will connect to a remote server on the specified host. This allows multiple clients to share the same hash equivalence data. + The remote server can be started manually through + the ``bin/bitbake-hashserv`` script provided by BitBake, + which supports UNIX domain sockets too. This script also allows + to start the server in read-only mode, to avoid accepting + equivalences that correspond to Share State caches that are + only available on specific clients. + + :term:`BB_HASHSERVE_UPSTREAM` + Specifies an upstream Hash Equivalence server. + + This optional setting is only useful when a local Hash Equivalence + server is started (setting :term:`BB_HASHSERVE` to ``auto``), + and you wish the local server to query an upstream server for + Hash Equivalence data. + + Example usage:: + + BB_HASHSERVE_UPSTREAM = "typhoon.yocto.io:8687" + :term:`BB_INVALIDCONF` Used in combination with the ``ConfigParsed`` event to trigger re-parsing the base metadata (i.e. all the recipes). The @@ -526,29 +549,6 @@ overview of their function and contents. - *clear* - Queries the source controls system every time. With this policy, there is no cache. The "clear" policy is the default. - :term:`BB_STAMP_POLICY` - Defines the mode used for how timestamps of stamp files are compared. - You can set the variable to one of the following modes: - - - *perfile* - Timestamp comparisons are only made between timestamps - of a specific recipe. This is the default mode. - - - *full* - Timestamp comparisons are made for all dependencies. - - - *whitelist* - Identical to "full" mode except timestamp - comparisons are made for recipes listed in the - :term:`BB_STAMP_WHITELIST` variable. - - .. note:: - - Stamp policies are largely obsolete with the introduction of - setscene tasks. - - :term:`BB_STAMP_WHITELIST` - Lists files whose stamp file timestamps are compared when the stamp - policy mode is set to "whitelist". For information on stamp policies, - see the :term:`BB_STAMP_POLICY` variable. - :term:`BB_STRICT_CHECKSUM` Sets a more strict checksum mechanism for non-local URLs. Setting this variable to a value causes BitBake to report an error if it @@ -1333,67 +1333,103 @@ overview of their function and contents. 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 :term:`SRC_URI` entry - that specifies that tarball. On the other hand, if the recipe or - append file needs to fetch a tarball and include a custom file, the - recipe or append file needs an :term:`SRC_URI` variable that specifies - all those sources. - - The following list explains the available URI protocols: + from the Internet, the recipe or append file uses a :term:`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 :term:`SRC_URI` + variable that specifies all those sources. + + 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 :ref:`bitbake-user-manual/bitbake-user-manual-fetching:fetchers` + section. - - ``file://`` : Fetches files, which are usually files shipped - with the metadata, from the local machine. The path is relative to - the :term:`FILESPATH` variable. + - ``az://`` : Fetches files from an Azure Storage account using HTTPS. - ``bzr://`` : Fetches files from a Bazaar revision control repository. - - ``git://`` : Fetches files from a Git revision control + - ``ccrc://`` - Fetches files from a ClearCase repository. + + - ``cvs://`` : Fetches files from a CVS revision control repository. - - ``osc://`` : Fetches files from an OSC (OpenSUSE Build service) - revision control repository. + - ``file://`` - Fetches files, which are usually files shipped + with the Metadata, from the local machine. + The path is relative to the :term:`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: - - ``repo://`` : Fetches files from a repo (Git) repository. + - ``${BPN}`` - The base recipe name without any special suffix + or version numbers. - - ``http://`` : Fetches files from the Internet using HTTP. + - ``${BP}`` - ``${BPN}-${PV}``. The base recipe name and + version but without any special package name suffix. - - ``https://`` : Fetches files from the Internet using HTTPS. + - *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. - - ``cvs://`` : Fetches files from a CVS revision control + - ``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. - - ``az://`` : Fetches files from an Azure Storage account using HTTPS. - Here are some additional options worth mentioning: - - ``unpack`` : Controls whether or not to unpack the file if it is - an archive. The default action is to unpack the file. + - ``downloadfilename`` : Specifies the filename used when storing + the downloaded file. + + - ``name`` - Specifies a name to be used for association with + :term:`SRC_URI` checksums or :term:`SRCREV` when you have more than one + file or git repository specified in :term:`SRC_URI`. For example:: + + SRC_URI = "git://example.com/foo.git;name=first \ + git://example.com/bar.git;name=second \ + http://example.com/file.tar.gz;name=third" + + SRCREV_first = "f1d2d2f924e986ac86fdf7b36c94bcdf32beec15" + SRCREV_second = "e242ed3bffccdf271b7fbaf34ed72d089537b42f" + SRC_URI[third.sha256sum] = "13550350a8681c84c861aac2e5b440161c2b33a3e4f302ac680ca5b686de48de" - ``subdir`` : Places the file (or extracts its contents) into the specified subdirectory. This option is useful for unusual tarballs or other archives that do not have their files already in a subdirectory within the archive. - - ``name`` : Specifies a name to be used for association with - :term:`SRC_URI` checksums when you have more than one file specified - in :term:`SRC_URI`. + - ``subpath`` - Limits the checkout to a specific subpath of the + tree when using the Git fetcher is used. - - ``downloadfilename`` : Specifies the filename used when storing - the downloaded file. + - ``unpack`` : Controls whether or not to unpack the file if it is + an archive. The default action is to unpack the file. :term:`SRCDATE` The date of the source code used to build the package. This variable |