diff --git a/documentation/sdk-manual/sdk-appendix-customizing.xml b/documentation/sdk-manual/sdk-appendix-customizing.xml
index 9fca16571f..79326077f5 100644
--- a/documentation/sdk-manual/sdk-appendix-customizing.xml
+++ b/documentation/sdk-manual/sdk-appendix-customizing.xml
@@ -382,614 +382,6 @@
-
-
- A Closer Look at devtool add
-
-
- The devtool add command automatically creates a
- recipe based on the source tree with which you provide it.
- Currently, the command has support for the following:
-
-
- Autotools (autoconf and
- automake)
-
-
- CMake
-
-
- Scons
-
-
- qmake
-
-
- Plain Makefile
-
-
- Out-of-tree kernel module
-
-
- Binary package (i.e. "-b" option)
-
-
- Node.js module through
- npm
-
-
- Python modules that use setuptools
- or distutils
-
-
-
-
-
- Apart from binary packages, the determination of how a source tree
- should be treated is automatic based on the files present within
- that source tree.
- For example, if a CMakeLists.txt file is found,
- then the source tree is assumed to be using
- CMake and is treated accordingly.
-
- In most cases, you need to edit the automatically generated
- recipe in order to make it build properly.
- Typically, you would go through several edit and build cycles
- until you can build the recipe.
- Once the recipe can be built, you could use possible further
- iterations to test the recipe on the target device.
-
-
-
-
- The remainder of this section covers specifics regarding how parts
- of the recipe are generated.
-
-
-
- Name and Version
-
-
- If you do not specify a name and version on the command
- line, devtool add attempts to determine
- the name and version of the software being built from
- various metadata within the source tree.
- Furthermore, the command sets the name of the created recipe
- file accordingly.
- If the name or version cannot be determined, the
- devtool add command prints an error and
- you must re-run the command with both the name and version
- or just the name or version specified.
-
-
-
- Sometimes the name or version determined from the source tree
- might be incorrect.
- For such a case, you must run the following commands:
-
- $ devtool reset -n recipename
-
- After running the devtool reset command,
- you need to run devtool add again and
- provide the name or the version.
-
-
-
-
- Dependency Detection and Mapping
-
-
- The devtool add command attempts to
- detect build-time dependencies and map them to other recipes
- in the system.
- During this mapping, the command fills in the names of those
- recipes in the
- DEPENDS
- value within the recipe.
- If a dependency cannot be mapped, then a comment is placed in
- the recipe indicating such.
- The inability to map a dependency might be caused because the
- naming is not recognized or because the dependency simply is
- not available.
- For cases where the dependency is not available, you must use
- the devtool add command to add an
- additional recipe to satisfy the dependency and then come
- back to the first recipe and add its name to
- DEPENDS.
-
-
-
- If you need to add runtime dependencies, you can do so by
- adding the following to your recipe:
-
- RDEPENDS_${PN} += "dependency1 dependency2 ..."
-
-
- The devtool add command often cannot
- distinguish between mandatory and optional dependencies.
- Consequently, some of the detected dependencies might
- in fact be optional.
- When in doubt, consult the documentation or the configure
- script for the software the recipe is building for further
- details.
- In some cases, you might find you can substitute the
- dependency for an option to disable the associated
- functionality passed to the configure script.
-
-
-
-
-
- License Detection
-
-
- The devtool add command attempts to
- determine if the software you are adding is able to be
- distributed under a common open-source license and sets the
- LICENSE
- value accordingly.
- You should double-check this value against the documentation
- or source files for the software you are building and update
- that LICENSE value if necessary.
-
-
-
- The devtool add command also sets the
- LIC_FILES_CHKSUM
- value to point to all files that appear to be license-related.
- However, license statements often appear in comments at the top
- of source files or within documentation.
- Consequently, you might need to amend the
- LIC_FILES_CHKSUM variable to point to one
- or more of those comments if present.
- Setting LIC_FILES_CHKSUM is particularly
- important for third-party software.
- The command attempts to ensure correct licensing should you
- upgrade the recipe to a newer upstream version in future.
- Any change in licensing is detected and you receive an error
- prompting you to check the license text again.
-
-
-
- If the devtool add command cannot
- determine licensing information, the
- LICENSE value is set to "CLOSED" and the
- LIC_FILES_CHKSUM vaule remains unset.
- This behavior allows you to continue with development but is
- unlikely to be correct in all cases.
- Consequently, you should check the documentation or source
- files for the software you are building to determine the actual
- license.
-
-
-
-
- Adding Makefile-Only Software
-
-
- The use of make by itself is very common
- in both proprietary and open source software.
- Unfortunately, Makefiles are often not written with
- cross-compilation in mind.
- Thus, devtool add often cannot do very
- much to ensure that these Makefiles build correctly.
- It is very common, for example, to explicitly call
- gcc instead of using the
- CC variable.
- Usually, in a cross-compilation environment,
- gcc is the compiler for the build host
- and the cross-compiler is named something similar to
- arm-poky-linux-gnueabi-gcc and might
- require some arguments (e.g. to point to the associated sysroot
- for the target machine).
-
-
-
- When writing a recipe for Makefile-only software, keep the
- following in mind:
-
-
- You probably need to patch the Makefile to use
- variables instead of hardcoding tools within the
- toolchain such as gcc and
- g++.
-
-
- The environment in which make runs
- is set up with various standard variables for
- compilation (e.g. CC,
- CXX, and so forth) in a similar
- manner to the environment set up by the SDK's
- environment setup script.
- One easy way to see these variables is to run the
- devtool build command on the
- recipe and then look in
- oe-logs/run.do_compile.
- Towards the top of this file you will see a list of
- environment variables that are being set.
- You can take advantage of these variables within the
- Makefile.
-
-
- If the Makefile sets a default for a variable, that
- default overrides the value set in the environment,
- which is usually not desirable.
- In this situation, you can either patch the Makefile
- so it sets the default using the "?=" operator, or
- you can alternatively force the value on the
- make command line.
- To force the value on the command line, add the
- variable setting to
- EXTRA_OEMAKE
- within the recipe as follows:
-
- EXTRA_OEMAKE += "'CC=${CC}' 'CXX=${CXX}'"
-
- In the above example, single quotes are used around the
- variable settings as the values are likely to contain
- spaces because required default options are passed to
- the compiler.
-
-
- Hardcoding paths inside Makefiles is often problematic
- in a cross-compilation environment.
- This is particularly true because those hardcoded paths
- often point to locations on the build host and thus
- will either be read-only or will introduce
- contamination into the cross-compilation by virtue of
- being specific to the build host rather than the target.
- Patching the Makefile to use prefix variables or other
- path variables is usually the way to handle this.
-
-
- Sometimes a Makefile runs target-specific commands such
- as ldconfig.
- For such cases, you might be able to simply apply
- patches that remove these commands from the Makefile.
-
-
-
-
-
-
- Adding Native Tools
-
-
- Often, you need to build additional tools that run on the
- build host system as opposed to the target.
- You should indicate this using one of the following methods
- when you run devtool add:
-
-
- Specify the name of the recipe such that it ends
- with "-native".
- Specifying the name like this produces a recipe that
- only builds for the build host.
-
-
- Specify the "‐‐also-native" option with the
- devtool add command.
- Specifying this option creates a recipe file that still
- builds for the target but also creates a variant with
- a "-native" suffix that builds for the build host.
-
-
-
- If you need to add a tool that is shipped as part of a
- source tree that builds code for the target, you can
- typically accomplish this by building the native and target
- parts separately rather than within the same compilation
- process.
- Realize though that with the "‐‐also-native" option, you
- can add the tool using just one recipe file.
-
-
-
-
-
- Adding Node.js Modules
-
-
- You can use the devtool add command in the
- following form to add Node.js modules:
-
- $ devtool add "npm://registry.npmjs.org;name=forever;version=0.15.1"
-
- The name and version parameters are mandatory.
- Lockdown and shrinkwrap files are generated and pointed to by
- the recipe in order to freeze the version that is fetched for
- the dependencies according to the first time.
- This also saves checksums that are verified on future fetches.
- Together, these behaviors ensure the reproducibility and
- integrity of the build.
- Notes
-
-
- You must use quotes around the URL.
- The devtool add does not require
- the quotes, but the shell considers ";" as a splitter
- between multiple commands.
- Thus, devtool add does not receive
- the other parts resulting in several "command not found"
- errors.
-
-
- In order to support adding
- Node.js modules, a
- nodejs recipe must be part of your
- SDK in order to provide Node.js
- itself.
-
-
-
-
-
-
-
-
- Working With Recipes
-
-
- When building a recipe with devtool build the
- typical workflow is as follows:
-
-
- Fetch the source
-
-
- Unpack the source
-
-
- Configure the source
-
-
- Compiling the source
-
-
- Install the build output
-
-
- Package the installed output
-
-
- For recipes in the workspace, fetching and unpacking is disabled
- as the source tree has already been prepared and is persistent.
- Each of these build steps is defined as a function, usually with a
- "do_" prefix.
- These functions are typically shell scripts but can instead be written
- in Python.
-
-
-
- If you look at the contents of a recipe, you will see that the
- recipe does not include complete instructions for building the
- software.
- Instead, common functionality is encapsulated in classes inherited
- with the inherit directive, leaving the recipe
- to describe just the things that are specific to the software to be
- built.
- A base
- class exists that is implicitly inherited by all recipes and provides
- the functionality that most typical recipes need.
-
-
-
- The remainder of this section presents information useful when
- working with recipes.
-
-
-
- Finding Logs and Work Files
-
-
- When you are debugging a recipe that you previously created using
- devtool add or whose source you are modifying
- by using the devtool modify command, after
- the first run of devtool build, you will
- find some symbolic links created within the source tree:
- oe-logs, which points to the directory in
- which log files and run scripts for each build step are created
- and oe-workdir, which points to the temporary
- work area for the recipe.
- You can use these links to get more information on what is
- happening at each build step.
-
-
-
- These locations under oe-workdir are
- particularly useful:
-
- image/:
- Contains all of the files installed at the
- do_install
- stage.
- Within a recipe, this directory is referred to by the
- expression
- ${D}.
-
- sysroot-destdir/:
- Contains a subset of files installed within
- do_install that have been put into the
- shared sysroot.
- For more information, see the
- "Sharing Files Between Recipes"
- section.
-
- packages-split/:
- Contains subdirectories for each package produced by the
- recipe. (more on "Packaging" below)
- For more information, see the
- "Packaging" section.
-
-
-
-
-
-
- Setting Configure Arguments
-
-
- If the software your recipe is building uses GNU autoconf,
- then a fixed set of arguments is passed to it to enable
- cross-compilation plus any extras specified by
- EXTRA_OECONF
- set within the recipe.
- If you wish to pass additional options, add them to
- EXTRA_OECONF.
- Other supported build tools have similar variables
- (e.g.
- EXTRA_OECMAKE
- for CMake,
- EXTRA_OESCONS
- for Scons, and so forth).
- If you need to pass anything on the make
- command line, you can use EXTRA_OEMAKE to do
- so.
-
-
-
- You can use the devtool configure-help command
- to help you set the arguments listed in the previous paragraph.
- The command determines the exact options being passed, and shows
- them to you along with any custom arguments specified through
- EXTRA_OECONF.
- If applicable, the command also shows you the output of the
- configure script's "‐‐help" option as a reference.
-
-
-
-
- Sharing Files Between Recipes
-
-
- Recipes often need to use files provided by other recipes on
- the build host.
- For example, an application linking to a common library needs
- access to the library itself and its associated headers.
- The way this access is accomplished within the extensible SDK is
- through the sysroot.
- One sysroot exists per "machine" for which the SDK is being built.
- In practical terms, this means a sysroot exists for the target
- machine, and a sysroot exists for the build host.
-
-
-
- Recipes should never write files directly into the sysroot.
- Instead, files should be installed into standard locations
- during the
- do_install
- task within the
- ${D}
- directory.
- A subset of these files automatically go into the sysroot.
- The reason for this limitation is that almost all files that go
- into the sysroot are cataloged in manifests in order to ensure
- they can be removed later when a a recipe is modified or removed.
- Thus, the sysroot is able to remain free from stale files.
-
-
-
-
- Packaging
-
-
- Packaging is not always particularly relevant within the
- extensible SDK.
- However, if you examine build output gets into the final image on
- the target device, it is important to understand packaging
- because the contents of the image are expressed in terms of
- packages ... not recipes.
-
-
-
- During the
- do_package
- task, files installed during the
- do_install
- task are split into one main package, which is almost always named
- the same as the recipe, and several other packages.
- This separation is done because not all of those installed files
- are always useful in every image.
- For example, you probably do not need any of the documentation
- installed in a production image.
- Consequently, for each recipe the documentation files are separated
- into a -doc package.
- Recipes that package software that has optional modules or
- plugins might do additional package splitting as well.
-
-
-
- After building a recipe you can see where files have gone by
- looking in the oe-workdir/packages-split
- directory, which contains a subdirectory for each package.
- Apart from some advanced cases, the
- PACKAGES
- and
- FILES
- variables controls splitting.
- The PACKAGES variable lists all of the
- packages to be produced, while the FILES
- variable specifies which files to include in each package,
- using an override to specify the package.
- For example, FILES_${PN} specifies the files
- to go into the main package (i.e. the main package is named the
- same as the recipe and
- ${PN}
- evaluates to the recipe name).
- The order of the PACKAGES value is significant.
- For each installed file, the first package whose
- FILES value matches the file is the package
- into which the file goes.
- Defaults exist for both the PACKAGES and
- FILES variables.
- Consequently, you might find you do not even need to set these
- variables in your recipe unless the software the recipe is
- building installs files into non-standard locations.
-
-
-
-
- Restoring the Target Device to its Original State
-
-
- If you use the devtool deploy-target
- command to write a recipe's build output to the target, and
- you are working on an existing component of the system, then you
- might find yourself in a situation where you need to restore the
- original files that existed prior to running the
- devtool deploy-target command.
- Because the devtool deploy-target command
- backs up any files it overwrites, you can use the
- devtool undeploy-target to restore those files
- and remove any other files the recipe deployed.
- Consider the following example:
-
- $ devtool undeploy-target lighttpd root@192.168.7.2
-
- If you have deployed multiple applications, you can remove them
- all at once thus restoring the target device back to its
- original state:
-
- $ devtool undeploy-target -a root@192.168.7.2
-
- Information about files deployed to the target as well as any
- backed up files are stored on the target itself.
- This storage of course requires some additional space
- on the target machine.
-
- The devtool deploy-target and
- devtool undeploy-target command do not
- currently interact with any package management system on the
- target device (e.g. RPM or OPKG).
- Consequently, you should not intermingle operations
- devtool deploy-target and the package
- manager operations on the target device.
- Doing so could result in a conflicting set of files.
-
-
-
-
-