ye is a command line tool to ease the manipulation of files under
the directory structure adopted by O.S. Systems to organize projects
that use the Yocto Project. ye provides means to quickly locate
files and directories into projects' directory tree, and act on them.
ye supports the legacy O.S. Systems layout:
<project>
.repo
<build dir>
setup-environment
sources
<project> is the root directory of the project you’ll be working on.
In it you’ll initially find a setup-environment script, which is
supposed to be source’d to set up the environment and will create
<build dir>, and a sources directory, under which the source code
of all projects (git repositories) will be stored.
The directory layout in the <build dir> directory follows the
standard layout as determined by the Yocto Project.
For current Yocto Project releases, ye also understands projects
set up with oe-init-build-env, OEROOT, <build dir>/conf/bblayers.conf,
and layer checkouts under either sources/ or layers/. If automatic
detection is not enough, YE_SOURCE_DIRS can be set to a colon-separated
list of layer or source directories.
In practice, ye determines the workspace in this order:
-
If
BUILDDIRis set, use it as the build directory. -
Otherwise, walk upward from the current directory until
conf/bblayers.confis found. -
If a repo workspace exists, use the directory containing
.repoas the project root. -
Prefer layer directories declared in
conf/bblayers.conf. -
If layer detection fails, fall back to
YE_SOURCE_DIRS,PLATFORM_ROOT_DIR,YE_TOPDIR,OEROOT,COREBASE, and common sibling directories such assources/,layers/,poky/, andopenembedded-core/.
Both single-quoted and double-quoted BBLAYERS values are supported.
This matters for current Yocto Project setups, whose generated
configuration files commonly use shell-like multi-line single-quoted
assignments.
Most ye commands accept a regular expression as argument. Thus, it’s
possible that it will obtain multiple results. In this case, if
ye's output is attached to a terminal (i.e., not a pipe or a file),
it will run interactively, prompting users for a specific result.
When running interactively, ye will paginate the output in case it
doesn’t fit the terminal window and will highlight matches in red on
the output.
Some commands expect the BUILDDIR environment variable to be set in
the environment (because they have to run bitbake behind the scenes
to find out things). This variable is automatically set by the
setup-environment script provided by O.S. Systems for Yocto
Project-based projects.
Commands that print matches are useful in scripts too. When stdout is
not a terminal, ye disables the interactive prompts and prints all
matches to stdout, except for shortcut commands such as view,
pkg-info, or pkg-extract, which perform their requested action
when a single unambiguous match exists.
ye is shipped as an executable Python script. It does not require a
Python package installation step; put the checkout directory in
PATH, or create a symlink to the ye executable from a directory
already in PATH.
Example:
$ export PATH=/path/to/ye:$PATH $ ye --help
For shell completion, source ye-completion.sh from your shell
startup file:
$ . /path/to/ye-completion.sh
The ye cd command needs to affect the current shell process, so it
is implemented by the ye-cd shell wrapper. Source it after ye is
available in PATH:
$ . /path/to/ye-cd
O.S. Systems' setup-environment script can do this automatically
when ye is present in the source tree. In other Yocto setups, add
the PATH, completion, and ye-cd lines to your preferred shell
startup file or project environment setup script.
-
Enter or source a Yocto build environment:
$ source oe-init-build-env
or, in O.S. Systems workspaces:
$ source setup-environment
-
Confirm
yecan see the build and configured layers:$ ye plumbing topdir $ ye f -e layer.conf
-
Find and open a recipe or configuration file:
$ ye f busybox $ ye v conf/machine/qemuarm.conf
-
Locate build output:
$ ye wd linux-yocto $ ye pf 'kernel_.*\.ipk' $ ye sf stdio.h
-
Inspect a package:
$ ye pi 'kernel_.*\.ipk' $ ye pv 'kernel-image.*\.ipk'
-
Use directory shortcuts by sourcing
ye-cd:$ . /path/to/ye-cd $ ye cd src $ ye cd wd linux-yocto
This section will show in detail how to use ye. The help message
displayed by ye when invoked with the --help option can be seen
below. The next subsections provide more detailed information about
each command.
$ ye -h
Usage: ye <command> [ <options> ]
f [-e] <regex>
find [-e] <regex>
Locate paths in configured Yocto layer/source directories that
match the given expression <regex>. <regex> is case insensitive
and implicitly surrounded by '.*'. -e disables the implicit use
of '.*' around the given <regex>. Note that, unless <regex>
contains /, matching is attempted on filenames only (not on
dirnames). If <regex> contains /, matching is attempted on the
full path.
v [-e] <regex>
view [-e] <regex>
Shortcut to find & view. If multiple files are found, a prompt for
files will be displayed (but not for actions).
e [-e] <regex>
edit [-e] <regex>
Shortcut to find & edit. If multiple files are found, a prompt for
files will be displayed (but not for actions).
sf [-e] <regex>
sysroot-find [-e] <regex>
Locate paths (in the "sysroots" directory) that match the given
expression <regex>. <regex> is case insensitive and implicitly
surrounded by '.*'. -e disables the implicit use of '.*' around
the given <regex>. Note that, unless <regex> contains /, matching
is attempted on filenames only (not on dirnames). If <regex>
contains /, matching is attempted on the full path.
wsf [-e] <regex>
work-shared-find [-e] <regex>
Similar to sysroot-find, but instead of searching in the sysroots
directories, search in the work-shared directory.
pf [-e] <regex>
pkg-find [-e] <regex>
Like 'find', but for packages.
pv [-e] <regex>
pkg-view [-e] <regex>
Shortcut to pkg-find & view. If multiple packages are found, a
prompt for packages will be displayed (but not for actions).
pi [-e] <regex>
pkg-info [-e] <regex>
Shortcut to pkg-find & info. If multiple packages are found, a
prompt for packages will be displayed (but not for actions).
ps [-e] <regex>
pkg-scripts [-e] <regex>
List scripts for package that matches <regex>. In case of multiple
matches, ye will prompt for a specific package. <regex> is case
insensitive and implicitly surrounded by '.*'. -e disables the
implicit use of '.*' around the given <regex>.
px [-e] [-c] <regex> [<file>]
pkg-extract [-e] [-c] <regex> [<file>]
Extract package that matches <regex>. In case of multiple matches,
ye will prompt for a specific package. <regex> is case insensitive
and implicitly surrounded by '.*'. -e disables the implicit use
of '.*' around the given <regex>.
If <file> is provided, ye will extract <file> only, otherwise the
whole package content will be extracted to a directory named after
the package filename (without extension). <file> must match the exact
file name in the package (usually starts with ./).
-c is specific to .deb and .ipk packages -- ye will extract files
from the control archive in packages.
wd [-e] <regex>
workdir [-e] <regex>
Locate the Yocto Project's workdir for <regex>. <regex> is
implicitly surrounded by '.*', unless -e is provided.
l [-e] [-H] [-R] <recipe pattern> [<log pattern>]
log [-e] [-H] <recipe pattern> [<log pattern>]
Show the log files for <recipe>. -e is only applied to
<recipe pattern>. <log pattern> is always implicitly surrounded
by '.*', if provided. If -H ("human readable") is given on the
command line, ye will try to make the lines that contain calls to
clang/clang++/gcc/g++ look more readable. If -R is provided, ye will apply
some text replacements to make the output more readable. Currently,
ye reverse expands some common variables whose expansion pollutes
log files with long paths. The following variables are reverse
expanded:
* $B
* $S
* $WORKDIR
* $TMPDIR
* $HOME
r [-e] <recipe pattern> [<run script pattern>]
run [-e] <recipe pattern> [<run script pattern>]
Show the log files for <recipe>. -e is only applied to
<recipe pattern>. <run script pattern> is always implicitly
surrounded by '.*', if provided.
g <args>
grep <args>
Run 'repo grep <args>' in repo-based workspaces, otherwise run
'git grep <args>' across configured layers.
sg <args>
sysroot-grep <args>
Run 'grep -r <args>' across available sysroot directories.
glg [-n <num commits>] [-i] <regex>
git-log-grep [-n <num commits>] [-i] <regex>
Run "git log -n <num commits> --oneline | grep <regex>" on all the
repositories and prompt the user for the commit to show.
If -n is not provided, 1000 will be used. If -i is provided, search
will be case insensitive.
gbh [<args>] <regex>
grep-buildhistory [<args>] <regex>
Run "git grep [<args>] <regex>" in the buildhistory directory.
bh [-d] <revisions back>
buildhistory [-d] <revisions back>
Show changes in buildhistory <revisions back> (a positive integer).
If -d is given, show the raw git diff output.
d [-e] <regex>
doc [-e] <regex>
Search variable names in the reference manual that match the given
expression <regex> and show the documentation for the selected
match. <regex> is case insensitive and implicitly surrounded by
'.*'. -e disables the implicit use of '.*' around the given
<regex>.
x <recipe> <variable>
expand <recipe> <variable>
Expand BitBake's variable <variable> in the context of <recipe> and
show the final value and the recursive expansion of all variables
and expressions involved.
cd [<dir shortcut>]
Change to <dir shortcut>. The following <dir shortcut> options are
available:
top
Change to project's TOPDIR
wd [<recipe>]
Change to <recipe>'s WORKDIR or to BUILDDIR/tmp/deploy/work if
<recipe> is not provided
bd
Change to BUILDDIR
bh
Change to the buildhistory directory
sd
Change to the sysroot directory for MACHINE
src [<recipe>]
Change to <recipe>'s source dir or to the detected source/layers
directory if <recipe> is not provided
img
Change to BUILDDIR/tmp/deploy/MACHINE/image/
pkg
Change to BUILDDIR/tmp/deploy/PKG_TYPE or its MACHINE subdir
manifest
Change to TOPDIR/.repo/manifests
When called without arguments, ye cd will change to BUILDDIR.
To use this feature, source'ing the ye-cd shell helper is required.
| Short | Long | Purpose |
|---|---|---|
|
|
Find files in configured Yocto layer/source directories. |
|
|
Find one file and open it with the configured pager. |
|
|
Find one file and open it with the configured editor. |
|
|
Find files in available sysroot directories. |
|
|
Find files in |
|
|
Find packages under |
|
|
List files contained in a package. |
|
|
Show package metadata. |
|
|
List package control scripts or control members. |
|
|
Extract package data files, or control files with |
|
|
Print recipe work directories under |
|
|
Open BitBake task logs. |
|
|
Open BitBake task run scripts. |
|
|
Search configured layers with |
|
|
Search text under available sysroot directories. |
|
|
Search git commit summaries across layer repositories. |
|
|
Run |
|
|
Show recent buildhistory changes. |
|
|
Search Yocto Project variable documentation. |
|
|
Expand BitBake variables and show recursive expansion. |
|
|
Change to common project/build directories through the |
ye provides commands to locate files and operate on them. Some
commands are specific to some directories and some are specific to
some file types (e.g., packages). The following sections provide a
more in-depth explanation about them.
The find command (short: f) can be used to locate files under the
configured Yocto layers. ye gets those layers from bblayers.conf
when possible, otherwise it falls back to legacy sources/, modern
layers/, OEROOT or YE_SOURCE_DIRS. Its argument is a regular
expression that will be matched against pathnames. If the given regex
does not contain /, matching is attempted on filenames only (not on
dirnames). If the given regex contains /, matching is attempted on
the full path.
After locating files that match the given pattern, ye will prompt
you to select one of the matches and, next, what to do with it. In
case the standard output is not a terminal (e.g., a file or a pipe),
interactive commands will just print the results to the standard
output (no prompt for action will be displayed).
Example:
$ ye f flex
[0] ~/yocto/sources/poky/meta/recipes-devtools/flex/flex.inc [0]
[1] ~/yocto/sources/poky/meta/recipes-devtools/flex/flex_2.5.35.bb [1]
Option (ENTER to cancel): 1
[v] View
[e] Edit
Option (ENTER to cancel): v
1 require flex.inc
2 PR = "r3"
3 LICENSE="BSD"
4 LIC_FILES_CHKSUM = "file://COPYING;md5=e4742cf92e89040b39486a6219b68067"
5 BBCLASSEXTEND = "native nativesdk"
6
7 SRC_URI += "file://avoid-FORTIFY-warnings.patch \
8 file://int-is-not-the-same-size-as-size_t.patch"
9
10 SRC_URI[md5sum] = "10714e50cea54dc7a227e3eddcd44d57"
11 SRC_URI[sha256sum] = "0becbd4b2b36b99c67f8c22ab98f7f80c9860aec70..."
|
Note
|
ye also allows you to use shortcuts for selecting options and
actions at the same prompt. In the example above, we typed 0 ENTER
to select flex.inc, then 0 ENTER to select the View action. The
shortcut would be 0v ENTER in the file selection prompt. For
Edit, the shortcut would be 0e ENTER.
|
For cases you know in advance what to do with files (i.e., view or
edit), ye provides commands to allow you to specify the action on
the command line, so it won’t prompt you for the action. Those
commands are view (short: v) and edit (short: e). They are
basically shortcuts to find → view and find → edit.
The view and edit commands can be quite handy when you have a part
of the full path to a file. Here’s an example use-case: you want to
understand how the qemuarm machine configuration is built. You
start by looking at the content of qemuarm.conf:
$ ye v qemuarm.conf
~/src/yocto/sources/poky/meta/conf/machine/qemuarm.conf
1 #@TYPE: Machine
2 #@NAME: arm_versatile_926ejs
3 #@DESCRIPTION: arm_versatile_926ejs
4
5 require conf/machine/include/qemu.inc
6 require conf/machine/include/tune-arm926ejs.inc
7 #require conf/machine/include/tune-arm1136jf-s.inc
8
9 KERNEL_IMAGETYPE = "zImage"
10
11 SERIAL_CONSOLE = "115200 ttyAMA0"
12
/home/mario/src/yocto/sources/poky/meta/conf/machine/qemuarm.conf
You see qemuarm.conf includes conf/machine/include/qemu.inc.
Since you may not know what layer ships
conf/machine/include/qemu.inc, to see its contents you first would
have to locate it, then you’d need to call a viewer passing as
argument the path to the file you found. With ye, you can just give
it the partial path referenced in qemuarm.conf:
$ ye v conf/machine/include/qemu.inc
~/src/yocto/sources/poky/meta/conf/machine/include/qemu.inc
1 PREFERRED_PROVIDER_virtual/xserver ?= "xserver-xorg"
2 PREFERRED_PROVIDER_virtual/egl ?= "mesa"
3 PREFERRED_PROVIDER_virtual/libgl ?= "mesa"
4 PREFERRED_PROVIDER_virtual/libgles1 ?= "mesa"
5 PREFERRED_PROVIDER_virtual/libgles2 ?= "mesa"
6
7 XSERVER ?= "xserver-xorg \
...
ye will locate and display the file in a single step. If it finds
multiple results for conf/machine/include/qemu.inc it’ll prompt you
for the one you really want to see.
The sysroot-find (short: sf) command is pretty much equivalent to
the find command, except it locates files under the sysroots
directories. Current Yocto releases primarily use
<build dir>/tmp/sysroots-components and per-recipe
recipe-sysroot directories; older <build dir>/tmp/sysroots trees
are still used as a fallback when present.
The work-shared-find (short: wsf) command is similar to the
sysroot-find command, but instead of searching in the sysroots
directories, it searches in the work-shared directory.
The pkg-find (short: pf) command is equivalent to the find
command, except it locates files under the deploy directory for
packages (<build dir>/tmp/deploy/<package type>). ye supports the
most common package formats generated by Yocto Project: .ipk, .deb
and .rpm.
For .ipk and .deb packages, ye reads the package as an ar
archive and then processes the embedded data.tar. or
control.tar. member. The following tar payload formats are
supported:
-
data.tar -
data.tar.gz -
data.tar.xz -
data.tar.zst -
control.tar -
control.tar.gz -
control.tar.xz -
control.tar.zst
The zstd variants are important for Scarthgap, Wrynose, and newer
Yocto Project releases where IPK package payloads can use
data.tar.zst. RPM packages are handled through rpm and
rpm2cpio.
The actions for packages are different from the find command. ye
supports the following actions on packages:
view-
show the package contents
info-
show the package metadata
scripts-
list package scripts (.e.g.,
postinstall,postrm) extract-
extract package contents to a directory named after the package filename
The pkg-extract command refuses to overwrite an existing extraction
directory. Run it from a scratch directory if you want to inspect a
package without modifying the build tree.
Just like the view and edit counterparts to the find command,
ye provides pkg-view (short: pv), pkg-info (short: pi),
pkg-scripts (short: ps) and pkg-extract (short: px) command
line shortcuts to the corresponding actions.
Examples:
$ ye pf busybox_ ~/yocto/build/tmp/deploy/ipk/cortexa9hf-vfp-neon/busybox_1.22.1-r32.5_cortexa9hf-vfp-neon.ipk [v] View [i] Info [s] Scripts [x] Extract Option (ENTER to cancel): v drwxrwxrwx root/root 0 2015-04-17 11:50 ./ drwxr-xr-x root/root 0 2015-04-17 11:50 ./etc/ -rw-r--r-- root/root 108 2015-04-17 11:50 ./etc/busybox.links.suid -rw-r--r-- root/root 2217 2015-04-17 11:50 ./etc/busybox.links.nosuid drwxr-xr-x root/root 0 2015-04-17 11:50 ./bin/ -rwxr-xr-x root/root 544012 2015-04-17 11:50 ./bin/busybox.nosuid -rwsr-xr-x root/root 52804 2015-04-17 11:50 ./bin/busybox.suid lrwxrwxrwx root/root 0 2015-04-17 11:50 ./bin/busybox -> busybox.nosuid lrwxrwxrwx root/root 0 2015-04-17 11:50 ./bin/sh -> busybox.nosuid /home/mario/yocto/build/tmp/deploy/ipk/cortexa9hf-vfp-neon/busybox_1.22.1-r32.5_cortexa9hf-vfp-neon.ipk
$ ye pi flex_ ~/yocto/build/tmp/deploy/ipk/cortexa9hf-vfp-neon/flex_2.5.39-r0.3_cortexa9hf-vfp-neon.ipk Package: flex Version: 2.5.39-r0.3 Description: Flex (The Fast Lexical Analyzer) Flex is a fast lexical analyser generator. Flex is a tool for generating programs that recognize lexical patterns in text. Section: devel Priority: optional Maintainer: O.S. Systems Software LTDA. <contato@ossystems.com.br> License: BSD Architecture: cortexa9hf-vfp-neon OE: flex Homepage: http://sourceforge.net/projects/flex/ Depends: m4, libc6 (>= 2.20) Source: http://downloads.sourceforge.net/flex/flex-2.5.39.tar.bz2 file://run-ptest file://do_not_create_pdf_doc.patch /home/mario/yocto/build/tmp/deploy/ipk/cortexa9hf-vfp-neon/flex_2.5.39-r0.3_cortexa9hf-vfp-neon.ipk
|
Tip
|
If you want to see the contents of the "main" package generated
by a recipe (i.e., not -dev, -dbg, -locale etc.), you can append
_ to the package name. So, instead of flex, you can use flex_
and ye won’t match flex-dev, for example.
|
The workdir command (short: wd) will print the work directory for
the given recipe regular expression pattern. Like the other commands
that deal with regular expressions, workdir implicitly surrounds the
given regular expression pattern by .*, unless the -e option is
provided.
Example:
$ ye wd busybox /home/mario/yocto/build/tmp/work/cortexa9hf-vfp-neon-oel-linux-gnueabi/busybox
Upon processing recipes, BitBake writes log files and scripts to the
directory where it processes recipes. Log files are prefixed by
log. and scripts are prefixed by run.:
run.<task>-
shows the code that was run to process
<task> log.<task>-
shows the output of the execution of
run.<task>
ye provides commands to display the contents of log files and
scripts: log (short: l) and run (short: r).
Both use as first argument a regex to be matched against recipe names.
The second argument (optional), is a regex to be matched against log
filenames or scripts. If the second argument is not provided, ye
will list all log files or scripts and prompt for the one you want to
see.
Both commands accept a -e option to indicate that the recipe regex
should not be automatically surrounded by .*.
Examples:
$ ye r base-files
=== Showing run scripts for base-files
[0] run.do_packagedata [0]
[1] run.do_package_write_ipk [1]
[2] run.do_fetch [2]
[3] run.do_install [3]
[4] run.do_unpack [4]
[5] run.do_populate_sysroot [5]
[6] run.do_patch [6]
[7] run.do_package [7]
[8] run.do_prepare_copyleft_sources [8]
[9] run.do_configure [9]
[10] run.do_populate_lic [10]
[11] run.do_compile [11]
[12] run.do_package_qa [12]
Option (ENTER to cancel): 11
1 #!/bin/sh
2
3 # Emit a useful diagnostic if something fails:
4 bb_exit_handler() {
5 ret=$?
...
$ ye l base-files
=== Showing logs for base-files
[0] log.do_package_qa [0]
[1] log.do_unpack [1]
[2] log.do_configure [2]
[3] log.do_prepare_copyleft_sources [3]
[4] log.do_fetch [4]
[5] log.do_package [5]
[6] log.do_populate_sysroot [6]
[7] log.do_patch [7]
[8] log.do_packagedata [8]
[9] log.do_compile [9]
[10] log.do_install [10]
[11] log.do_populate_lic [11]
[12] log.do_package_write_ipk [12]
Option (ENTER to cancel): 11
1 DEBUG: Executing python function sstate_task_prefunc
2 DEBUG: Python function sstate_task_prefunc finished
...
$ ye r base-files pack
=== Showing run scripts for base-files
[0] run.do_packagedata [0]
[1] run.do_package_write_ipk [1]
[2] run.do_unpack [2]
[3] run.do_package [3]
[4] run.do_package_qa [4]
Option (ENTER to cancel): 4
1 def do_package_qa(d):
2 import subprocess
3 import oe.packagedata
4
...
The log command also handles the -H option, which tries to make
compiler command lines more readable (and numbers them). It
recognizes common C/C compiler invocations such as `gcc`, `g,
`clang, and clang++. See some examples below:
Without -H:
$ ye l busybox compile === Showing logs for busybox [0] log.do_compile_ptest_base [0] [1] log.do_compile [1] Option (ENTER to cancel): 1 ... 1118 gcc -Wp,-MD,applets/.applet_tables.d -Wall -Wstrict-prototypes -O2 -fomit-frame-pointer -o applets/applet_tables applets/applet_tables.c ...
With -H
$ ye l -H busybox compile === Showing logs for busybox [0] log.do_compile_ptest_base [0] [1] log.do_compile [1] Option (ENTER to cancel): 1 ... --------------[ command line 2 ]---------------------- gcc -Wp,-MD,applets/.applet_tables.d -Wall -Wstrict-prototypes -O2 -fomit-frame-pointer -o applets/applet_tables applets/applet_tables.c ...
Long paths can considerably clutter logs, making them quite difficult
to read. Another useful argument to log is -R: it reverse expands
some variables in log text, transforming long paths into their
corresponding variable. Examples:
Without -R:
$ ye l -H make$ compile ... Making all in doc make[2]: Entering directory '/home/mario/src/yocto/build/tmp/work/ppce500v2-oel-linux-gnuspe/make/4.0-r0/build/doc' make[2]: Leaving directory '/home/mario/src/yocto/build/tmp/work/ppce500v2-oel-linux-gnuspe/make/4.0-r0/build/doc' make[2]: Entering directory '/home/mario/src/yocto/build/tmp/work/ppce500v2-oel-linux-gnuspe/make/4.0-r0/build' ---------------[ command line 1 ]--------------- powerpc-oel-linux-gnuspe-gcc -m32 -mcpu=8548 -mabi=spe -mspe -mfloat-gprs=double --sysroot=/home/mario/src/yocto/build/tmp/sysroots/olt8820plus -DLOCALEDIR=\"/usr/share/locale\" -DLIBDIR=\"/usr/lib\" -DINCLUDEDIR=\"/usr/include\" -DHAVE_CONFIG_H -I. -I/home/mario/src/yocto/build/tmp/work/ppce500v2-oel-linux-gnuspe/make/4.0-r0/make-4.0 -O2 -pipe -g -feliminate-unused-debug-types -c -o ar.o /home/mario/src/yocto/build/tmp/work/ppce500v2-oel-linux-gnuspe/make/4.0-r0/make-4.0/ar.c ...
With -R:
$ ye l -H -R make$ compile ... Making all in doc make[2]: Entering directory '$B/doc' make[2]: Leaving directory '$B/doc' make[2]: Entering directory '$B' ---------------[ command line 1 ]--------------- powerpc-iep-linux-gnuspe-gcc -m32 -mcpu=8548 -mabi=spe -mspe -mfloat-gprs=double --sysroot=$TMPDIR/sysroots/olt8820plus -DLOCALEDIR=\"/usr/share/locale\" -DLIBDIR=\"/usr/lib\" -DINCLUDEDIR=\"/usr/include\" -DHAVE_CONFIG_H -I. -I$S -O2 -pipe -g -feliminate-unused-debug-types -c -o ar.o $S/ar.c ...
ye provides commands to locate text in file contents and on summary
lines of commit messages. The next subsections show these commands in
detail.
The grep command searches configured Yocto layers. In legacy
repo-based workspaces it uses repo grep; otherwise it runs git grep
across detected layer repositories. If the layers are not git
repositories, it falls back to recursive grep.
The grep command will pass the arguments provided on the command
line to the underlying grep command and will prompt you to select one
of the matches, then the action to apply on the selected file. In
case of a single match, you’ll be only prompted for the action.
Example:
$ ye g -i libfoo
[0] sources/meta-openembedded/meta-oe/recipes-connectivity/samba/samba-3.6.24/waf-as-source.patch:+ """example: bld.symlink_as('${PREFIX}/lib/libfoo.so', 'libfoo.so.1.2.3') """ [0]
[1] sources/meta-openembedded/meta-oe/recipes-connectivity/samba/samba-3.6.24/waf-as-source.patch:+ libfoo.so is installed as libfoo.so.1.2.3 [1]
[2] sources/poky/meta/classes/package.bbclass: # /opt/abc/lib/libfoo.so.1 and contains /usr/bin/abc depending on system library libfoo.so.1 [2]
[3] sources/poky/meta/recipes-core/glibc/glibc/eglibc-install-pic-archives.patch: # $(inst_libdir)/libfoo.so -- for linking, symlink or ld script [3]
[4] sources/poky/meta/recipes-core/glibc/glibc/eglibc-install-pic-archives.patch: # $(inst_slibdir)/libfoo.so.NN -- for loading by SONAME, symlink [4]
Option (ENTER to cancel): 2v
1 #
2 # Packaging process
3 #
4 # Executive summary: This class iterates over the functions listed in PACKAGEFUNCS
...
The sysroot-grep (short: sg) command is similar to the grep
command, but instead of searching for matches in source directories,
it recursively searches for matches in available sysroot directories.
Example:
$ ye sg -i '<libfoo\.a>'
Parsing recipes..done.
[0] /home/mario/src/reach/dizzy/build/tmp/sysroots/g2h-solo-3/usr/lib/perl/ptest/lib/ExtUtils/Liblist.pm:you are using GCC, it gets translated to C<libfoo.a>, but for other win32 [0]
[1] /home/mario/src/reach/dizzy/build/tmp/sysroots/g2h-solo-3/usr/lib/perl/ptest/cpan/ExtUtils-MakeMaker/lib/ExtUtils/Liblist.pm:you are using GCC, it gets translated to C<libfoo.a>, but for other win32 [1]
[2] /home/mario/src/reach/dizzy/build/tmp/sysroots/g2h-solo-3/usr/lib/perl/5.20.0/ExtUtils/Liblist.pm:you are using GCC, it gets translated to C<libfoo.a>, but for other win32 [2]
Option (ENTER to cancel): 1v
1 package ExtUtils::Liblist;
2
3 use strict;
4
...
The git-log-grep command (short: glg) basically runs
git log --oneline | grep <regex>
for the given regular expressions on the summary lines of all git
repositories that are part of the project. By default, it limits the
repository history to 1000 commits. If you need to search in older
commit summary lines, you can use the -n <num commits> option.
Example:
$ ye glg 'build error'
[0] poky 7eb3e45 bitbake: toasterui: refactor log saving and save out-of-build errors [0]
[1] meta-fsl-arm e45b4f8 linux-imx (2.6.35.3): Fix build errors when using make 3.82 [1]
[2] meta-fsl-arm 7b30034 gst-fsl-plugin-2.0.3: fix build error due to missing uint declaration [2]
[3] meta-fsl-arm c38a612 xf86-video-imxfb: fix build error due to missing uint declaration [3]
[4] meta-openembedded 17ce4c6 libmtp: Fix 'Makefile.am: No such file or directory' build error. [4]
Option (ENTER to cancel): 4
commit 17ce4c6ac0d5b3651c7bd8758511679210a3286c
Author: Charles Oram <charles@oram.co.nz>
Date: Wed May 14 15:36:45 2014 +1200
libmtp: Fix 'Makefile.am: No such file or directory' build error.
* skip_udev_rules_generation() needs to reference Makefile.am in the recipe
source directory.
Signed-off-by: Charles Oram <charles@oram.co.nz>
Signed-off-by: Martin Jansa <Martin.Jansa@gmail.com>
diff --git a/meta-oe/recipes-connectivity/libmtp/libmtp_1.1.5.bb b/meta-oe/recipes-connectivity/libmtp/libmtp_1.1.5.bb
index f4ea800..0c92ff9 100644
--- a/meta-oe/recipes-connectivity/libmtp/libmtp_1.1.5.bb
+++ b/meta-oe/recipes-connectivity/libmtp/libmtp_1.1.5.bb
@@ -29,8 +29,8 @@ do_unpack[vardeps] += "skip_udev_rules_generation"
do_unpack[postfuncs] += "skip_udev_rules_generation"
skip_udev_rules_generation () {
- sed -i -e '/^noinst_DATA=/,/util\/mtp-hotplug -H/d' Makefile.am
- cp ${WORKDIR}/69-libmtp.rules ${S}/
+ sed -i -e '/^noinst_DATA=/,/util\/mtp-hotplug -H/d' ${S}/Makefile.am
+ cp ${WORKDIR}/69-libmtp.rules ${S}/
}
inherit autotools pkgconfig lib_package
The grep-buildhistory command (short: gbh) is a wrapper around
git grep in the buildhistory directory.
Example:
$ ye gbh 'passwd /bin/busybox' [0] packages/armv7a-vfp-neon-iep-linux-gnueabi/busybox/busybox/latest.pkg_postinst: update-alternatives --install /usr/bin/passwd passwd /bin/busybox.suid 50 [0] [1] packages/armv7a-vfp-neon-iep-linux-gnueabi/busybox/busybox/latest.pkg_postrm: update-alternatives --remove passwd /bin/busybox.suid [1] [2] packages/ppce500v2-iep-linux-gnuspe/busybox/busybox/latest.pkg_postinst: update-alternatives --install /usr/bin/passwd passwd /bin/busybox.suid 50 [2] [3] packages/ppce500v2-iep-linux-gnuspe/busybox/busybox/latest.pkg_postrm: update-alternatives --remove passwd /bin/busybox.suid [3]
The buildhistory command (short: bh) can be used to display
changes in the
buildhistory.
The required argument (a positive integer) is the number of previous
revisions to display. If the optional -d argument is given,
buildhistory will show the raw diff output.
buildhistory is basically a wrapper around buildhistory-diff or
git diff in the buildhistory directory (when -d is provided).
Example:
$ ye bh 1 packages/cortexa9hf-vfp-neon-oel-linux-gnueabi/tslib/tslib-calibrate: PKGR changed from r0.2 to r0.3 packages/cortexa9hf-vfp-neon-oel-linux-gnueabi/tslib/tslib-conf: PKGR changed from r0.2 to r0.3 packages/cortexa9hf-vfp-neon-oel-linux-gnueabi/tslib/tslib-dbg: PKGR changed from r0.2 to r0.3 packages/cortexa9hf-vfp-neon-oel-linux-gnueabi/tslib/tslib-dev: PKGR changed from r0.2 to r0.3 packages/cortexa9hf-vfp-neon-oel-linux-gnueabi/tslib/tslib-doc: PKGR changed from r0.2 to r0.3 packages/cortexa9hf-vfp-neon-oel-linux-gnueabi/tslib/tslib-locale: PKGR changed from r0.2 to r0.3 packages/cortexa9hf-vfp-neon-oel-linux-gnueabi/tslib/tslib-staticdev: PKGR changed from r0.2 to r0.3 packages/cortexa9hf-vfp-neon-oel-linux-gnueabi/tslib/tslib-tests: PKGR changed from r0.2 to r0.3 packages/cortexa9hf-vfp-neon-oel-linux-gnueabi/tslib/tslib: PKGR changed from r0.2 to r0.3
The doc command (short: d) is a man-like tool for Yocto
Project’s variables. It searches the
Yocto
Project Reference Manual for variables matching the given regular
expression pattern (matching is case-insensitive).
Example:
$ ye d STAGING_DIR [0] STAGING_DIR [0] [1] STAGING_DIR_TARGET [1] [2] STAGING_DIR_HOST [2] [3] STAGING_DIR_NATIVE [3] Option (ENTER to cancel): 3 === STAGING_DIR_NATIVE Specifies the path to the sysroot directory for the build host.
ye maintains a cache of the Yocto project Reference Manual for seven
days (under $HOME/.ye/doc-data). If the cache is older than seven
days, it will fetch the reference manual data and update the cache.
The expand command (short: x) can be very handy to find out
variables' values and how they are assembled. It takes as argument a
recipe and the variable you want to expand. It’ll print the final
variable value and the intermediary expansions (in case the variable
value references other variables) in the context of the given recipe.
Example:
$ ye x core-image-minimal STAGING_DIR_TARGET
Parsing recipes..done.
=== Final value
STAGING_DIR_TARGET = /home/mario/src/yocto/build/tmp/sysroots/nitrogen6x-lite
=== Expansion
STAGING_DIR_TARGET ==> ${STAGING_DIR}/${MACHINE}
STAGING_DIR ==> ${TMPDIR}/sysroots
TMPDIR ==> /home/mario/src/yocto/build/tmp
MACHINE ==> nitrogen6x-lite
Most build-output commands expect the BUILDDIR environment variable
to be set in the environment. This variable is set by the usual Yocto
environment setup scripts. If it is not set, ye will also try to
detect a build directory by walking up from the current directory until
it finds conf/bblayers.conf.
The expand command starts BitBake through Tinfoil. It therefore has
the same constraints as other BitBake clients: it needs a valid build
environment and may fail if another process is holding the same
BitBake server in an incompatible state.
The cd command can be used to move around the project directory.
ye provides some shortcut names for common directories in the layout
adopted by O.S. Systems. See the documentation for the cd command
for all available shortcuts.
Using the cd command is just like using the shell’s cd command,
but giving the available shortcuts as arguments. Examples:
$ pwd /home/mario/src/yocto $ ye cd $ pwd /home/mario/src/yocto/build $ ye cd src $ pwd /home/mario/src/yocto/sources $ ye cd src flex [0] ~/src/yocto/sources/poky/meta/recipes-bsp/grub/files/fix-issue-with-flex-2.5.37.patch [0] [1] ~/src/yocto/sources/poky/meta/recipes-devtools/flex/flex_2.5.39.bb [1] [2] ~/src/yocto/sources/poky/meta/recipes-devtools/flex/flex.inc [2] Option (ENTER to cancel): 0 /home/mario/src/yocto/sources/poky/meta/recipes-bsp/grub/files/fix-issue-with-flex-2.5.37.patch $ pwd /home/mario/src/yocto/sources/poky/meta/recipes-bsp/grub/files $ ye cd wd flex [0] /home/mario/src/yocto/build/tmp/work/x86_64-linux/flex-native [0] [1] /home/mario/src/yocto/build/tmp/work/cortexa9hf-vfp-neon-poky-linux-gnueabi/flex [1] Option (ENTER to cancel): 1 /home/mario/src/yocto/build/tmp/work/cortexa9hf-vfp-neon-poky-linux-gnueabi/flex $ pwd /home/mario/src/yocto/build/tmp/work/cortexa9hf-vfp-neon-poky-linux-gnueabi/flex
|
Note
|
the cd command requires evaluating the ye-cd shell wrapper
that is shipped with ye. O.S. Systems' setup-environment script
will do that automatically if you have ye in your source tree.
|
ye is configured through environment variables.
| Variable | Meaning |
|---|---|
|
Yocto build directory. If unset, |
|
Colon-separated list of layer/source directories. This overrides automatic source discovery. |
|
Project root hint used by O.S. Systems environments. |
|
Project root hint used when automatic discovery is not enough. |
|
OpenEmbedded-Core or Poky root hint, usually set by |
|
OpenEmbedded-Core base directory hint. |
|
Command template used to view files. Use |
|
Fallback pager when |
|
Command used to edit files. |
|
Fallback editor when |
For the editor, ye first checks if YE_EDITOR is set in the
environment. If it is not set, it checks the EDITOR environment
variable. If neither is set, it searches for a usable terminal editor
in this order: emacs -nw, mg, zile, qemacs, nano, vim,
and vi. If no editor is found, ye prints an error.
For the pager, ye first checks if YE_PAGER is set in the
environment. If it is not set, it checks the PAGER environment
variable. If it is not set, it resorts to less -N %s. If less
cannot be found, you’ll get an error.
%s can be used as a placeholder for the file to act upon.
ye stores cached documentation and shell plumbing files below
$HOME/.ye.
ye is intended to work with both older O.S. Systems Yocto layouts
and current Yocto Project layouts. The compatibility-sensitive areas
are source/layer discovery, sysroot discovery, and package archive
format support.
- Kirkstone 4.0 LTS
-
Compatible for the tested surfaces. The older
tmp/sysrootslayout remains supported as a fallback. - Scarthgap 5.0 LTS
-
Compatible for source discovery, workdir lookup, sysroot lookup, and package discovery. IPK zstd payloads are supported through
data.tar.zst. - Wrynose 6.0 LTS
-
Compatible for the tested surfaces in a Wrynose build tree using
PACKAGE_CLASSES = "package_ipk".yecorrectly handles configured layers from single-quotedBBLAYERS, per-recipe sysroots,tmp/sysroots-components, and zstd-compressed IPK payloads.
When migrating between Yocto releases, pay special attention to:
-
package payload compression (
data.tar.zstfor modern IPK output); -
source layout changes around
WORKDIRandUNPACKDIR; -
whether the build setup still creates
conf/bblayers.conf; -
whether package, image, sysroot, and buildhistory directories exist in the expected build directory.
A Python 3 installation and a Yocto Project build tree are required.
Use the Python version supported by your Yocto release. ye supports
both the legacy O.S. Systems .repo/sources layout and current
Yocto layouts that expose layers through conf/bblayers.conf.
Core host tools:
-
git -
grep -
lessor another pager -
a terminal editor for
ye edit -
arand GNUtarfor.deband.ipkinspection -
zstdor GNUtarwith zstd support for modern.ipkpayloads -
rpmandrpm2cpiofor RPM package inspection/extraction
Optional host tools:
-
repo, for legacy repo-based workspace grep support -
buildhistory-diff, for formatted buildhistory output
For the doc command, the lxml module for Python is
required.
For the cd command, a Bourne-compatible shell is required.
The lightweight checks below are useful before changing ye:
$ python3 -m py_compile ye ye_compat.py bb-expand-vars.py format-command-lines.py setup-environment.d/ye.py $ bash -n ye-cd $ bash -n ye-completion.sh
Package archive selection is covered by test_ye_packages.py:
$ python3 -B test_ye_packages.py
Useful smoke tests in a real build tree:
$ ye --help $ ye plumbing topdir $ ye f -e layer.conf $ ye wd -e linux-yocto $ ye pf -e 'kernel_.*\.ipk' $ ye pi -e 'kernel_.*\.ipk' $ ye pv -e 'kernel-image.*\.ipk' $ ye sf stdio.h
Commands that call BitBake, such as ye expand and ye plumbing x,
should be treated as integration tests. They need a working BitBake
server and a valid build environment.
yesearches too many files or files from unconfigured layers-
Check
conf/bblayers.confandYE_SOURCE_DIRS.yeprefers configuredBBLAYERS; if parsing fails or no layer exists, it falls back to broader source directories. ERROR: Could not determine the Yocto Project’s build directory.-
Run from inside the build directory, set
BUILDDIR, or source the Yocto setup script again. pkg-viewreports an unsupported compression type-
Confirm the package members with
ar t <package>. Supported.deband.ipkdata/control archives are uncompressed tar, gzip, xz, and zstd tar files. pkg-extractrefuses to run because the output directory exists-
yenever clobbers extraction directories. Remove or rename the existing directory, or run the command from a scratch directory. doccannot update documentation data-
The
doccommand needs Pythonlxmland network access when its cache under$HOME/.ye/doc-datais missing or older than seven days. expandorplumbing xcannot start BitBake-
Ensure the Yocto environment is sourced and that no incompatible BitBake server is active for the same build directory.
Some ye commands use bitbake behind the scenes, and since
bitbake doesn’t support running multiple instances in parallel under
the same build directory, some ye features may not work while you
are using bitbake.
ye is a navigation and inspection helper. It does not replace
BitBake, devtool, package managers, or release migration tools; it
uses the build tree that those tools create.