From patchwork Tue Oct 21 18:28:32 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Adam Blank X-Patchwork-Id: 72771 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from aws-us-west-2-korg-lkml-1.web.codeaurora.org (localhost.localdomain [127.0.0.1]) by smtp.lore.kernel.org (Postfix) with ESMTP id C7986CCD1A5 for ; Tue, 21 Oct 2025 18:29:56 +0000 (UTC) Received: from mail-ej1-f46.google.com (mail-ej1-f46.google.com [209.85.218.46]) by mx.groups.io with SMTP id smtpd.web10.20570.1761071393416144821 for ; Tue, 21 Oct 2025 11:29:53 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@gmail.com header.s=20230601 header.b=gRAypF/t; spf=pass (domain: gmail.com, ip: 209.85.218.46, mailfrom: adam.blank.g@gmail.com) Received: by mail-ej1-f46.google.com with SMTP id a640c23a62f3a-b3f5e0e2bf7so1226096366b.3 for ; Tue, 21 Oct 2025 11:29:53 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1761071392; x=1761676192; darn=lists.openembedded.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=DXvmfESRxNtg9fgt/TY5148YzCRNeYFUs1NPw/I5ySY=; b=gRAypF/t2Uh0K0CV1nq+zSKtaZ7slM5+V0inSBkqRyYh/PLBXWkx9NH0J7+jc/T/zS 8u4gIpw8GkxMzSN0Hs6/q+Mle/ziHMPlT5HLgOvkfJuXSGiw0hi6apkV8yHZO1wW7tCi dYpmioZVD0yEUHFVtarIld5G78Acz+ek3V0HwDaognrR2LWPdMu56tVggbZnY9lZlw0K B8pEX4k0ourCqCJ4k1MrVKywG30sO31ZcJZwvVtD/UDlZQg91Xn8zVln02IoZ5P31Ssv IVXqeX/yobVG/jSbTQeAciTYwbY+kn15n3YeXT6ho9+JeJW0hopu+T4zPsElUYDe0YNy Rtmw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1761071392; x=1761676192; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=DXvmfESRxNtg9fgt/TY5148YzCRNeYFUs1NPw/I5ySY=; b=l4foWyoKpI05+j2xYnj4L4RGtJkIgBhSfcUhyxnjwJ/X1oWHOklAjvG/Betud24j+p ZnX0AfL1gILhoHOgBerVxzJfQdKiHl6RSlaTm3i6QgWrLAD/mI9Xbl++hDOAwGxTOz3m dils5/20kgVb/gJDpJisjZXSzWnnOOK0p1r/BYe19faMAw9k25qzjo99/C5oMVtBo7yQ WO0L0kcK9e0hrnzJSN/MYZWN8S+JN49q3aXRFWOoN7kaLAIhJ5ZK1G5xQIEP0tzZpvwi lDBc5KCDLIRV41dDvL99/tScL+WEgH+dI5yvfXwM887EU/sE0bIn9vu79lsIegzKZQyD EXNg== X-Gm-Message-State: AOJu0Yztz+3lynNdkk7y3Ln0Xmyd0g7C1GQoWq9cTcCYLGhyxK4I2HUu UFEoMLWrzJyw6Gp+nCQIIzBNGZMyCaJef4lCwYl0gXhFJBVJSn5UN3MSsBnZQg== X-Gm-Gg: ASbGncvNSHsCobVjw5vceZBBmflnELFLydrzqL+hGddzLNKdb/pFE8N3rjLX8O4cX+q /pKeyneXRnFR7UpYMaT71qpcqUuhl/ecXwQG2PCLtz2AP66HuH8tmWZbRPCNa+0Tq/PN88p4Ezu Aqd4/CnJV4Qqfn408Tm0PggZ7BNu1AI1NUzDdW68H8P6xCCMBL/WjxMpvDMI5ElFCs3rzRySxKP hHe9A6ToMkCmJSUMcwL6VMR1zcGzhVoJY/sr3oDH1sDiffQ2xZdVCIu/OWy0zmYhozvQTKKhjdj gsruiXjB0G1JIQ5YUfmMfYRJ7e2Mhawhah5mswEdThrZDwkzOj4WbfLDrtEKpjEOXi7KCXq9tx9 0aMYBbHCbnShzRqXZrxbOpXvl+WdIQ8qZekLdXOIjfBCLvC3bqiSh8wJS/FyS3QyVSlYt71ICxe a0PPZ9PhvPZmejn5SEtzWe X-Google-Smtp-Source: AGHT+IEOo6eCOSyNCprMcSNAQEh5FJcediWDtVvll1jTGDDv7eF1X+pUXFmPg+ZFSv1i9T2Apf/dKQ== X-Received: by 2002:a17:907:3f04:b0:b3f:a960:e057 with SMTP id a640c23a62f3a-b64749411b1mr2269258666b.31.1761071391552; Tue, 21 Oct 2025 11:29:51 -0700 (PDT) Received: from localhost.localdomain ([2a02:a312:c8a8:7a00:564c:7f09:5ade:5a5e]) by smtp.gmail.com with ESMTPSA id a640c23a62f3a-b65eb036846sm1151383166b.54.2025.10.21.11.29.50 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 21 Oct 2025 11:29:51 -0700 (PDT) From: Adam Blank To: bitbake-devel@lists.openembedded.org Cc: Adam Blank Subject: [PATCH 1/3] doc: bitbake-user-manual: describe UNPACKDIR in fetching Date: Tue, 21 Oct 2025 20:28:32 +0200 Message-ID: <20251021182834.11403-2-adam.blank.g@gmail.com> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20251021182834.11403-1-adam.blank.g@gmail.com> References: <20251021182834.11403-1-adam.blank.g@gmail.com> MIME-Version: 1.0 List-Id: X-Webhook-Received: from li982-79.members.linode.com [45.33.32.79] by aws-us-west-2-korg-lkml-1.web.codeaurora.org with HTTPS for ; Tue, 21 Oct 2025 18:29:56 -0000 X-Groupsio-URL: https://lists.openembedded.org/g/bitbake-devel/message/18198 Signed-off-by: Adam Blank --- doc/bitbake-user-manual/bitbake-user-manual-fetching.rst | 8 +++++--- .../bitbake-user-manual-ref-variables.rst | 4 ++++ 2 files changed, 9 insertions(+), 3 deletions(-) diff --git a/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst b/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst index f357765b7..d10d2f611 100644 --- a/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst +++ b/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst @@ -42,7 +42,7 @@ The instantiation of the fetch class is usually followed by:: rootdir = l.getVar('UNPACKDIR') fetcher.unpack(rootdir) -This code unpacks the downloaded files to the specified by ``UNPACKDIR``. +This code unpacks the downloaded files to the specified :term:`UNPACKDIR`. .. note:: @@ -51,7 +51,7 @@ This code unpacks the downloaded files to the specified by ``UNPACKDIR``. examine the OpenEmbedded class file ``base.bbclass`` . -The :term:`SRC_URI` and ``UNPACKDIR`` variables are not hardcoded into the +The :term:`SRC_URI` and :term:`UNPACKDIR` variables are not hardcoded into the fetcher, since those fetcher methods can be (and are) called with different variable names. In OpenEmbedded for example, the shared state (sstate) code uses the fetch module to fetch the sstate files. @@ -606,7 +606,9 @@ password, and fetches a Revision based on a Label:: .. note:: - You should always set S to "${UNPACKDIR}/p4" in your recipe. + Your recipe should always set S as shown in the following example:: + + S = "${UNPACKDIR}/p4" By default, the fetcher strips the depot location from the local file paths. In the above example, the content of ``example-depot/main/source/`` will be placed diff --git a/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst b/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst index 810f88689..e50b71380 100644 --- a/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst +++ b/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst @@ -1697,3 +1697,7 @@ overview of their function and contents. :term:`TOPDIR` Points to the build directory. BitBake automatically sets this variable. + + :term:`UNPACKDIR` + The directory into which recipe's downloads are unpacked during its + build process. From patchwork Tue Oct 21 18:28:33 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Adam Blank X-Patchwork-Id: 72773 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from aws-us-west-2-korg-lkml-1.web.codeaurora.org (localhost.localdomain [127.0.0.1]) by smtp.lore.kernel.org (Postfix) with ESMTP id B417DCCD1AF for ; Tue, 21 Oct 2025 18:30:06 +0000 (UTC) Received: from mail-ed1-f53.google.com (mail-ed1-f53.google.com [209.85.208.53]) by mx.groups.io with SMTP id smtpd.web10.20572.1761071396454143356 for ; Tue, 21 Oct 2025 11:29:56 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@gmail.com header.s=20230601 header.b=kD4Z0EOV; spf=pass (domain: gmail.com, ip: 209.85.208.53, mailfrom: adam.blank.g@gmail.com) Received: by mail-ed1-f53.google.com with SMTP id 4fb4d7f45d1cf-63c4c346bd9so6969287a12.0 for ; Tue, 21 Oct 2025 11:29:56 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1761071395; x=1761676195; darn=lists.openembedded.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=I7kWp/hQ5KCjmgYPA6qbidYAdxfuPY34KMUCtoqAN/A=; b=kD4Z0EOV0vCVCcfbbY9w7bIcphQ1sH7FBNVitc/KFXhC4awJB1G/qL9QeuO9QMGiwG lliP+p5wB9GQY2nglowLGuZB6G7gImT/XPqjSJuQWtnUT2x4TyC0OhsCuATDcPR6i71M SRJpw/9j0LFQfUZcY0RLrq5m94+NFnLWHy0/AtTwz7HLg5RdKkqaboJ3AcPVbGgk9S7l HIWpeMHKf9cR/doLzmnOjQsEmBwB4CL06N661phRXIzUIgF8fqcyuqVbCoiLhvLmQVyg MZCr2BHnW8NXApwsPNt2pdq86HEG+yh8MDEZLecoPBbBGsDFva6D0eAjf6IHHL7Ung01 sGCw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1761071395; x=1761676195; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=I7kWp/hQ5KCjmgYPA6qbidYAdxfuPY34KMUCtoqAN/A=; b=DHO1GO0VeVy/f5M+wDyKJL4Of4zeeuV2i3ChuajTT9xxvaGbwRN0lFTwECoTnZ4RUw GZfUAs/iBKRk7MjfiQgbnqy80fphG/Bey5D1KuITMaWWkiv4imMB3cm3zgdDNi6gbSw8 s8aSI97vqnaTgVFAwGgY4HBDeCmrAl5sh6LohJ7ws00YFi6pjakC++uNzGr1oXz7obIp /AQ+tcy+xZd5b0HLVAsWMQqCLb91KbAdBa/s+xdPqWrqM9zLXgjJN0POQMCwNMcNQ6Fx 8ncjmq1dLxespn360WrBi9Mt5lxV9scrGEuDhsu5mBi3aakDVKg3qhAazTFZcCA2LZdl UTiQ== X-Gm-Message-State: AOJu0YxVb3wIH+RfHleILFqGN4AbJb7cxyjSvgJes3fUEVP29GWljSRD dCbqDN4coXGRRxi/qZ/gZVYqoXtGoG9wWrEg93E6u806iLRWZdd06aJ+yBHmyA== X-Gm-Gg: ASbGncvYafCmVGweKyIVFoW2qLZZX+6ibwdm+jKNXU45IbE5frUSiuGcY4VrshrjYvH cLgZzP8wioijIWrMJctgIyMDaX6w7UWokkjZ2Z6hT0D7G4bHVJK5LqZKjHlYapDc+IdE/Xp5sXj iUMx3ZUBAjI57sNE6NKVjyxb3QxVqvpDTfEiUGVE5w9DxG8Dj/8GU8RqskRIFs8ok9ZYjV/aaT+ KDIZkpvqbCU0PhyLkcjCj/OgUILJEgRoBu721K03LXPK7cmWCXzu57CuQcDKfFRYG/UaVgwpvDG WM5/dbzKuJuEsekjqMS3DXNHQ2SyBO8d4yUYviksvNSj2piccQohqO9ozBnF+TZgbHeDs+AeGKi UkPJ5uKaRRv+jN6H0r8gHKae1rENUBUXLrq5dZtCeC0FE/wiLXVtCTbiwB/wSIEgMZcCXvO0woO ne/APGPVHujpFUId4KAA1nldDgq6eRns0= X-Google-Smtp-Source: AGHT+IFa9xyOihH4sSZoT7TDrHhdDdgb1Kky6kSzbh6wNAukhTw1dLYO9ad4KZJrD58XaaENoMbXag== X-Received: by 2002:a17:906:40d5:b0:b65:f5a6:68aa with SMTP id a640c23a62f3a-b65f5a66b4dmr1320725766b.16.1761071394415; Tue, 21 Oct 2025 11:29:54 -0700 (PDT) Received: from localhost.localdomain ([2a02:a312:c8a8:7a00:564c:7f09:5ade:5a5e]) by smtp.gmail.com with ESMTPSA id a640c23a62f3a-b65eb036846sm1151383166b.54.2025.10.21.11.29.53 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 21 Oct 2025 11:29:54 -0700 (PDT) From: Adam Blank To: bitbake-devel@lists.openembedded.org Cc: Adam Blank Subject: [PATCH 2/3] doc: bitbake-user-manual: AUTOREV and SRCREV_FORMAT roles in fetching Date: Tue, 21 Oct 2025 20:28:33 +0200 Message-ID: <20251021182834.11403-3-adam.blank.g@gmail.com> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20251021182834.11403-1-adam.blank.g@gmail.com> References: <20251021182834.11403-1-adam.blank.g@gmail.com> MIME-Version: 1.0 List-Id: X-Webhook-Received: from li982-79.members.linode.com [45.33.32.79] by aws-us-west-2-korg-lkml-1.web.codeaurora.org with HTTPS for ; Tue, 21 Oct 2025 18:30:06 -0000 X-Groupsio-URL: https://lists.openembedded.org/g/bitbake-devel/message/18199 Describe the roles of AUTOREV and SRCREV_FORMAT in the fetching step. Add their missing descriptions to the variable reference section. Fixes [YOCTO #14498] Signed-off-by: Adam Blank --- .../bitbake-user-manual-fetching.rst | 46 ++++++++++++++++++- .../bitbake-user-manual-ref-variables.rst | 15 ++++-- 2 files changed, 56 insertions(+), 5 deletions(-) diff --git a/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst b/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst index d10d2f611..dbb52e85a 100644 --- a/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst +++ b/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst @@ -173,6 +173,11 @@ govern the behavior of the unpack stage: - *subdir:* Unpacks the specific URL to the specified subdirectory within the root directory. +- *name:* Assigns a name to a given component of the :term:`SRC_URI`. + This component is later referenced by this name when specifying its + :term:`SRCREV` or :term:`SRC_URI` checksum, or to correctly place its + revision in the package version string with aid of :term:`SRCREV_FORMAT`. + The unpack call automatically decompresses and extracts files with ".Z", ".z", ".gz", ".xz", ".zip", ".jar", ".ipk", ".rpm". ".srpm", ".deb" and ".bz2" extensions as well as various combinations of tarball extensions. @@ -453,7 +458,7 @@ This fetcher supports the following parameters: 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" + HEAD as the revision for use with :term:`AUTOREV`. The "usehead" parameter implies no branch and only works when the transfer protocol is ``file://``. @@ -845,4 +850,41 @@ submodules. However, you might find the code helpful and readable. Auto Revisions ============== -We need to document ``AUTOREV`` and :term:`SRCREV_FORMAT` here. +For recipes which need to use the latest revision of their source code, +the way to achieve it is to use :term:`AUTOREV` as the value of the +source code repository's :term:`SRCREV`:: + + SRCREV = "${AUTOREV}" + +.. note:: + + With :term:`AUTOREV`, BitBake will always need to take the additional step of + querying the remote repository to retrieve the latest available revision. + + Also, recipes using it don't benefit from the caching mechanism. + +Multiple Source Control Repositories +==================================== + +For some recipes it is necessary to make use of more than one +version controlled source code repository. In such case, the recipe +must provide BitBake with information about how it should include +the different SCM revisions in its package version string, instead of its +usual approach with a single :term:`SRCREV`. + +For this purpose, the recipe must set the :term:`SRCREV_FORMAT` +variable. Consider the following example:: + + SRC_URI = " \ + git://git.some.example.com/source-tree.git;name=machine \ + git://git.some.example.com/metadata.git;name=meta \ + " + SRCREV_machine = "3f9db490a81eeb0077be3c5a5aa1388a2372232f" + SRCREV_meta = "1ac1d0ff730fe1dd1371823d562db8126750a98c" + SRCREV_FORMAT ?= "meta_machine" + +The value given to :term:`SRCREV_FORMAT` references names, which were +assigned using the ``name`` parameter in the :term:`SRC_URI` definition, +and which represent the version controlled source code repositories. +In the above example, the :term:`SRC_URI` contained two URLs named +"meta" and "machine". diff --git a/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst b/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst index e50b71380..7c864b69a 100644 --- a/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst +++ b/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst @@ -36,6 +36,14 @@ overview of their function and contents. when specified allows for the Git binary from the host to be used rather than building ``git-native``. + :term:`AUTOREV` + This is a special variable used during fetching. When :term:`SRCREV` is + set to the value of this variable, the latest revision from the version + controlled source code repository is used. + It should be set as follows:: + + SRCREV = "${AUTOREV}" + :term:`AZ_SAS` Azure Storage Shared Access Signature, when using the :ref:`Azure Storage fetcher ` @@ -1622,7 +1630,8 @@ overview of their function and contents. - ``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:: + file or source control repository specified in :term:`SRC_URI`. + For example:: SRC_URI = "git://example.com/foo.git;branch=main;name=first \ git://example.com/bar.git;branch=main;name=second \ @@ -1657,11 +1666,11 @@ overview of their function and contents. identifier and not just a tag. :term:`SRCREV_FORMAT` - Helps construct valid :term:`SRCREV` values when + Helps construct a valid package version string when multiple source controlled URLs are used in :term:`SRC_URI`. - The system needs help constructing these values under these + The system needs help constructing this value under these circumstances. Each component in the :term:`SRC_URI` is assigned a name and these are referenced in the :term:`SRCREV_FORMAT` variable. Consider an example with URLs named "machine" and "meta". In this case, From patchwork Tue Oct 21 18:28:34 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Adam Blank X-Patchwork-Id: 72772 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from aws-us-west-2-korg-lkml-1.web.codeaurora.org (localhost.localdomain [127.0.0.1]) by smtp.lore.kernel.org (Postfix) with ESMTP id B41C3CCD1B9 for ; Tue, 21 Oct 2025 18:30:06 +0000 (UTC) Received: from mail-ed1-f53.google.com (mail-ed1-f53.google.com [209.85.208.53]) by mx.groups.io with SMTP id smtpd.web11.20639.1761071398760216488 for ; Tue, 21 Oct 2025 11:29:59 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@gmail.com header.s=20230601 header.b=Q4Hztndg; spf=pass (domain: gmail.com, ip: 209.85.208.53, mailfrom: adam.blank.g@gmail.com) Received: by mail-ed1-f53.google.com with SMTP id 4fb4d7f45d1cf-63b9da57cecso10146381a12.0 for ; Tue, 21 Oct 2025 11:29:58 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1761071397; x=1761676197; darn=lists.openembedded.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=jTuDGp7V+A+Ilgalo/4QXAtydtp6D4lLXImQZq/bxhc=; b=Q4HztndgdrhpHxEvxtGsTthTj5wbbPkTqDGE3lw5M0gT+4B0L8OOvdOgzhBeo9B5+T 2RGAaXD6IK67LPYr0rau0/rvPRMin3DHySyialLy5W41BYz8qVE/jG0sbbNsXJWbYD2X HBcy5AupODOg7x1kGTVwCbdSSfO6Er9DFMB5LqW++usdWC91b0lXltUYmaA4hZtJAUWU 68Q96dGOLDMvqebXUnICWN1O5rHs464zPtqhzxTS25tXruGsxzpNsNc3xEOtstiSteqC JlJFLP2VFTFHeXR22vX4EkK+8sjYMBISEXKbIVI4WxhHdm1tWlBDgFFASCPvSMFInPjv mYTQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1761071397; x=1761676197; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=jTuDGp7V+A+Ilgalo/4QXAtydtp6D4lLXImQZq/bxhc=; b=n80i+v/5HwN0LrXMhMlZ6LnW9EETz64AcP2hcF4meXcdTBuv/pSig5Y2fygQvQqAVV mTbY+T+B6Ls1ipZnXRuhs8xD+6Vuurc6MltMWM7PUJpVBEU2w2zpV8/KkEW++o5uxSh6 WXOo5D0rA+EaOLUL3oMqwAQVC8fNTMa/ZYuEYfnbUJVLuaxOaYC3T0S6c00XBuHQ7bCK pSxQWZ8+fmGoXt0SQkZNTuZgCUw2u7AM7X+enlFR+IFulGvnLjJG0FqNAo1oNOcFM5zt FwHegwtHEPH9AafgOqH4BeGsEPvNyTvyuLpqzBPoi3PTvIhpxgQMp5ktv1tC7zD9Q1Rx yU9g== X-Gm-Message-State: AOJu0YxmHnOaNsEKcNliJ1rm6cBG1jaXZe2K4x28EgykeMpvgjL0LSZ4 A2T4U6HfXxS8g6bYthLidAGIr61C48/OfcG7GgtvFqdX3R2UEUG+mz3qmIXrIQ== X-Gm-Gg: ASbGncstv8Pl4xkTSpYshB/BACPf+2MPLZJVF6uUQsG31G3HPXFr/TjsQOS049KBtXa SfrCBDMUrKZ1DqvU1ijD8+/uSiOBhe++USbRUtY95S3nIT1UCc3yPIQ+phxRUsSf/aYmn7JJORl uNdNBakjsGJH8cgGgFraxoZTEOScobMiQC+ITuYTFNEy21NQUt2lsvDajMZCOEiDFUQI2qAYi3x RQsNap4KFB/EMLCJpgP1yIMX00Prpc48Zp57kB9JjgItENS6eZWDbkolbmAP/5HSK2ks1QswYkk 2qMPAIW+XROirlYQkdZuwXlVLth4boYIpped+CYQF8f848jb4TrDCfmwNqk3Gat+NNamg58oNrf Qvicwu5x0M57f9/IwuTfH3EDRB7VLmORl3IgzGtKYa6SNvzlIweUwgBXCNmhZhz9YRxJjkexPtd OTxmTPQmEFo+cWb00Y0dPz6jVs9oNPp0k= X-Google-Smtp-Source: AGHT+IFja3TOkO4AwiqPLU+eq3xz7ALopBpctRLZ1cM2ZQGaZLHa7uHswGt3qmQgADbUk7oeUs3sNQ== X-Received: by 2002:a17:907:7f8a:b0:b62:2352:5043 with SMTP id a640c23a62f3a-b6474940cd5mr2003484066b.46.1761071396666; Tue, 21 Oct 2025 11:29:56 -0700 (PDT) Received: from localhost.localdomain ([2a02:a312:c8a8:7a00:564c:7f09:5ade:5a5e]) by smtp.gmail.com with ESMTPSA id a640c23a62f3a-b65eb036846sm1151383166b.54.2025.10.21.11.29.55 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 21 Oct 2025 11:29:56 -0700 (PDT) From: Adam Blank To: bitbake-devel@lists.openembedded.org Cc: Adam Blank Subject: [PATCH 3/3] doc: bitbake-user-manual: style and completeness corrections Date: Tue, 21 Oct 2025 20:28:34 +0200 Message-ID: <20251021182834.11403-4-adam.blank.g@gmail.com> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20251021182834.11403-1-adam.blank.g@gmail.com> References: <20251021182834.11403-1-adam.blank.g@gmail.com> MIME-Version: 1.0 List-Id: X-Webhook-Received: from li982-79.members.linode.com [45.33.32.79] by aws-us-west-2-korg-lkml-1.web.codeaurora.org with HTTPS for ; Tue, 21 Oct 2025 18:30:06 -0000 X-Groupsio-URL: https://lists.openembedded.org/g/bitbake-devel/message/18200 Fix encountered style issues in the fetching section. Mention that "subdir" and fetcher specific parameters can stack-up. Signed-off-by: Adam Blank --- .../bitbake-user-manual-fetching.rst | 67 +++++++++---------- .../bitbake-user-manual-ref-variables.rst | 3 +- 2 files changed, 35 insertions(+), 35 deletions(-) diff --git a/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst b/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst index dbb52e85a..fe23c7620 100644 --- a/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst +++ b/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst @@ -159,21 +159,22 @@ URLs except Git URLs, BitBake uses the common ``unpack`` method. A number of parameters exist that you can specify within the URL to govern the behavior of the unpack stage: -- *unpack:* Controls whether the URL components are unpacked. If set to +- *"unpack":* Controls whether the URL components are unpacked. If set to "1", which is the default, the components are unpacked. If set to "0", the unpack stage leaves the file alone. This parameter is useful when you want an archive to be copied in and not be unpacked. -- *dos:* Applies to ``.zip`` and ``.jar`` files and specifies whether +- *"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 +- *"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. +- *"subdir":* Unpacks the specific URL to the specified subdirectory + within the specified root directory. This path can be further modified + by fetcher specific parameters. -- *name:* Assigns a name to a given component of the :term:`SRC_URI`. +- *"name":* Assigns a name to a given component of the :term:`SRC_URI`. This component is later referenced by this name when specifying its :term:`SRCREV` or :term:`SRC_URI` checksum, or to correctly place its revision in the package version string with aid of :term:`SRCREV_FORMAT`. @@ -251,21 +252,19 @@ Some example URLs are as follows:: introduce ambiguity when parsing URLs that also contain semi-colons, for example:: - SRC_URI = "http://abc123.org/git/?p=gcc/gcc.git;a=snapshot;h=a5dd47" - + SRC_URI = "http://abc123.org/git/?p=gcc/gcc.git;a=snapshot;h=a5dd47" Such URLs should should be modified by replacing semi-colons with '&' characters:: - SRC_URI = "http://abc123.org/git/?p=gcc/gcc.git&a=snapshot&h=a5dd47" - + SRC_URI = "http://abc123.org/git/?p=gcc/gcc.git&a=snapshot&h=a5dd47" In most cases this should work. Treating semi-colons and '&' in queries identically is recommended by the World Wide Web Consortium (W3C). Note that due to the nature of the URL, you may have to specify the name of the downloaded file as well:: - SRC_URI = "http://abc123.org/git/?p=gcc/gcc.git&a=snapshot&h=a5dd47;downloadfilename=myfile.bz2" + SRC_URI = "http://abc123.org/git/?p=gcc/gcc.git&a=snapshot&h=a5dd47;downloadfilename=myfile.bz2" .. _cvs-fetcher: @@ -403,16 +402,16 @@ This fetcher supports the following parameters: .. 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:: + 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;branch=main;protocol=ssh;..." + SRC_URI = "git://git@gitlab.freedesktop.org/mesa/mesa.git;branch=main;protocol=ssh;..." - Note the ``:`` character changed for a ``/`` before the path to the project. + 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 @@ -530,10 +529,10 @@ The fetcher uses the ``rcleartool`` or Following are options for the :term:`SRC_URI` statement: -- *vob*: The name, which must include the prepending "/" character, +- *"vob":*: The name, which must include the prepending "/" character, of the ClearCase VOB. This option is required. -- *module*: The module, which must include the prepending "/" +- *"module":*: The module, which must include the prepending "/" character, in the selected VOB. .. note:: @@ -545,7 +544,7 @@ Following are options for the :term:`SRC_URI` statement: load /example_vob/example_module -- *proto*: The protocol, which can be either ``http`` or ``https``. +- *"proto"*: The protocol, which can be either ``http`` or ``https``. By default, the fetcher creates a configuration specification. If you want this specification written to an area other than the default, use @@ -554,9 +553,9 @@ the specification is written. .. note:: - the SRCREV loses its functionality if you specify this variable. However, - SRCREV is still used to label the archive after a fetch even though it does - not define what is fetched. + the :term:`SRCREV` loses its functionality if you specify this variable. + However, :term:`SRCREV` is still used to label the archive after a fetch even + though it does not define what is fetched. Here are a couple of other behaviors worth mentioning: @@ -620,14 +619,14 @@ the above example, the content of ``example-depot/main/source/`` will be placed in ``${UNPACKDIR}/p4``. For situations where preserving parts of the remote depot paths locally is desirable, the fetcher supports two parameters: -- *"module":* - The top-level depot location or directory to fetch. The value of this - parameter can also point to a single file within the depot, in which case - the local file path will include the module path. -- *"remotepath":* - When used with the value "``keep``", the fetcher will mirror the full depot - paths locally for the specified location, even in combination with the - ``module`` parameter. +- *"module":* + The top-level depot location or directory to fetch. The value of this + parameter can also point to a single file within the depot, in which case + the local file path will include the module path. +- *"remotepath":* + When used with the value "``keep``", the fetcher will mirror the full depot + paths locally for the specified location, even in combination with the + ``module`` parameter. Here is an example use of the the ``module`` parameter:: diff --git a/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst b/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst index 7c864b69a..8993bab87 100644 --- a/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst +++ b/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst @@ -1644,7 +1644,8 @@ overview of their function and contents. - ``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. + subdirectory within the archive. This path can be further modified + by fetcher specific parameters. - ``subpath``: Limits the checkout to a specific subpath of the tree when using the Git fetcher is used.