jeans/motioneyeos
jeans/motioneyeos
1
0
Fork 0
mirror of https://github.com/motioneye-project/motioneyeos.git synced 2025-07-27 21:26:36 +00:00
Code Issues Packages Projects Releases Wiki Activity

manual/user guide/customization: rework section on rootfs customization

Browse Source 
This patch reworks the section on root filesystem customization as follows:
- use labeled list instead of bulleted list to clarify the different methods
- move rootfs overlay and post-build scripts to the top and label them as
  recommended.
- split post-image to a separate section, as it is not related to the target
  filesystem customization
- line up post-build and post-image explanations, for example regarding
  working directory of the script
- general expansion of some of the explanation
- general rewording

Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
Signed-off-by: Peter Korsgaard <peter@korsgaard.com>
This commit is contained in:
Thomas De Schampheleire 2014-08-31 15:14:30 +02:00 committed by Peter Korsgaard
parent 24534eb40a
commit 44a5c46213
3 changed files with 121 additions and 71 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

37
docs/manual/customize-post-image.txt Normal file
View File

@ -0,0 +1,37 @@
// -*- mode:doc; -*-
// vim: set syntax=asciidoc:
=== Customization _after_ the images have been created
While post-build scripts (xref:rootfs-custom[]) are run _before_
building the filesystem image, kernel and bootloader, *post-image
scripts* can be used to perform some specific actions _after_ all images
have been created.
Post-image scripts can for example be used to automatically extract your
root filesystem tarball in a location exported by your NFS server, or
to create a special firmware image that bundles your root filesystem and
kernel image, or any other custom action required for your project.
To enable this feature, specify a space-separated list of post-image
scripts in config option +BR2_ROOTFS_POST_IMAGE_SCRIPT+ (in the +System
configuration+ menu). If you specify a relative path, it will be
relative to the root of the Buildroot tree.
Just like post-build scripts, post-image scripts are run with the main
Buildroot tree as current working directory. The path to the +images+
output directory is passed as the first argument to each script. If the
config option +BR2_ROOTFS_POST_SCRIPT_ARGS+ is not empty, these
arguments will be passed to the script too. All the scripts will be
passed the exact same set of arguments, it is not possible to pass
different sets of arguments to each script.
Again just like for the post-build scripts, the scripts have access to
the environment variables +BR2_CONFIG+, +HOST_DIR+, +STAGING_DIR+,
+TARGET_DIR+, +BUILD_DIR+, +BINARIES_DIR+ and +BASE_DIR+.
The post-image scripts will be executed as the user that executes
Buildroot, which should normally _not_ be the root user. Therefore, any
action requiring root permissions in one of these scripts will require
special handling (usage of fakeroot or sudo), which is left to the
script developer.

153
docs/manual/customize-rootfs.txt
View File

@ -4,85 +4,96 @@
[[rootfs-custom]] [[rootfs-custom]]
=== Customizing the generated target filesystem === Customizing the generated target filesystem
Besides changing one or another configuration through +make *config+, Besides changing the configuration through +make *config+,
there are a few ways to customize the resulting target filesystem. there are a few other ways to customize the resulting target filesystem.
* Customize the target filesystem directly and rebuild the image. The The two recommended methods, which can co-exist, are root filesystem
target filesystem is available under +output/target/+. You can overlay(s) and post build script(s).
simply make your changes here and run make afterwards - this will
rebuild the target filesystem image. This method allows you to do
anything to the target filesystem, but if you decide to completely
rebuild your toolchain and tools, these changes will be lost. This
solution is therefore only useful for quick tests only: _changes do
not survive the +make clean+ command_. Once you have validated your
changes, you should make sure that they will persist after a +make
clean+ by using one of the following methods.
* Create a filesystem overlay: a tree of files that are copied directly Root filesystem overlays (+BR2_ROOTFS_OVERLAY+)::
over the target filesystem after it has been built. Set +
+BR2_ROOTFS_OVERLAY+ to the top of the tree. +.git+, +.svn+, +.hg+ A filesystem overlay is a tree of files that is copied directly
directories, +.empty+ files and files ending with +~+ are excluded. over the target filesystem after it has been built. To enable this
_Among these first 3 methods, this one should be preferred_. feature, set config option +BR2_ROOTFS_OVERLAY+ (in the +System
configuration+ menu) to the root of the overlay. You can even specify
multiple overlays, space-separated. If you specify a relative path,
it will be relative to the root of the Buildroot tree. Hidden
directories of version control systems, like +.git+, +.svn+, +.hg+,
etc., files called +.empty+ and files ending in +~+ are excluded from
the copy.
* In the Buildroot configuration, you can specify the paths to one or Post-build scripts (+BR2_ROOTFS_POST_BUILD_SCRIPT+)::
more *post-build scripts*. These scripts are called in the given order, +
'after' Buildroot builds all the selected software, but 'before' the Post-build scripts are shell scripts called 'after' Buildroot builds
rootfs images are assembled. The +BR2_ROOTFS_POST_BUILD_SCRIPT+ allows all the selected software, but 'before' the rootfs images are
you to specify the location of your post-build scripts. This option can be assembled. To enable this feature, specify a space-separated list of
found in the +System configuration+ menu. The destination root post-build scripts in config option +BR2_ROOTFS_POST_BUILD_SCRIPT+ (in
filesystem folder is given as the first argument to these scripts, the +System configuration+ menu). If you specify a relative path, it
and these scripts can then be used to remove or modify any file in your will be relative to the root of the Buildroot tree.
+
Using post-build scripts, you can remove or modify any file in your
target filesystem. You should, however, use this feature with care. target filesystem. You should, however, use this feature with care.
Whenever you find that a certain package generates wrong or unneeded Whenever you find that a certain package generates wrong or unneeded
files, you should fix that package rather than work around it with some files, you should fix that package rather than work around it with some
post-build cleanup scripts. post-build cleanup scripts.
You may also use these variables in your post-build script: +
- +BR2_CONFIG+: the path to the Buildroot .config file The post-build scripts are run with the main Buildroot tree as current
- +HOST_DIR+, +STAGING_DIR+, +TARGET_DIR+: see working directory. The path to the target filesystem is passed as the
xref:generic-package-reference[] first argument to each script. If the config option
- +BUILD_DIR+: the directory where packages are extracted and built +BR2_ROOTFS_POST_SCRIPT_ARGS+ is not empty, these arguments will be
- +BINARIES_DIR+: the place where all binary files (aka images) are passed to the script too. All the scripts will be passed the exact
stored same set of arguments, it is not possible to pass different sets of
- +BASE_DIR+: the base output directory arguments to each script.
+
In addition, you may also use these environment variables:
* Create your own 'target skeleton'. You can start with the default - +BR2_CONFIG+: the path to the Buildroot .config file
skeleton available under +system/skeleton+ and then customize it to - +HOST_DIR+, +STAGING_DIR+, +TARGET_DIR+: see
suit your needs. The +BR2_ROOTFS_SKELETON_CUSTOM+ and xref:generic-package-reference[]
+BR2_ROOTFS_SKELETON_CUSTOM_PATH+ will allow you to specify the - +BUILD_DIR+: the directory where packages are extracted and built
location of your custom skeleton. These options can be found in the - +BINARIES_DIR+: the place where all binary files (aka images) are
+System configuration+ menu. At build time, the contents of the stored
skeleton are copied to output/target before any package - +BASE_DIR+: the base output directory
installation. Note that this method is *not recommended*, as it
duplicates the entire skeleton, which prevents from taking advantage
of the fixes or improvements brought to the default Buildroot
skeleton. The recommended method is to use the _post-build scripts_
mechanism described in the previous item.
Note also that you can use the *post-image scripts* Below two more methods of customizing the target filesystem are
if you want to perform some specific actions 'after' all described, but they are not recommended.
filesystem images have been created (for example to automatically
extract your root filesystem tarball in a location exported by your
NFS server, or to create a special firmware image that bundles your
root filesystem and kernel image, or any other custom action), you can
specify a space-separated list of scripts in the
+BR2_ROOTFS_POST_IMAGE_SCRIPT+ configuration option. This option can be
found in the +System configuration+ menu as well.
Each of those scripts will be called with the path to the +images+ Direct modification of the target filesystem::
output directory as first argument, and will be executed with the main +
Buildroot source directory as the current directory. Those scripts will For temporary modifications, you can modify the target filesystem
be executed as the user that executes Buildroot, which should normally directly and rebuild the image. The target filesystem is available
not be the root user. Therefore, any action requiring root permissions under +output/target/+. After making your changes, run +make+ to
in one of these _post-image scripts_ will require special handling rebuild the target filesystem image.
(usage of fakeroot or sudo), which is left to the script developer. +
This method allows you to do anything to the target filesystem, but if
you need to clean your Buildroot tree using +make clean+, these
changes will be lost. Such cleaning is necessary in several cases,
refer to xref:full-rebuild[] for details. This solution is therefore
only useful for quick tests: _changes do not survive the +make clean+
command_. Once you have validated your changes, you should make sure
that they will persist after a +make clean+, using a root filesystem
overlay or a post-build script.
Just like for the _post-build scripts_ mentioned above, you also have Custom target skeleton (+BR2_ROOTFS_SKELETON_CUSTOM+)::
access to the following environment variables from your _post-image +
scripts_: +BR2_CONFIG+, +BUILD_DIR+, +HOST_DIR+, +STAGING_DIR+, The root filesystem image is created from a target skeleton, on top of
+TARGET_DIR+, +BINARIES_DIR+ and +BASE_DIR+. which all packages install their files. The skeleton is copied to the
target directory +output/target+ before any package is built and
Additionally, each of the +BR2_ROOTFS_POST_BUILD_SCRIPT+ and installed. The default target skeleton provides the standard Unix
+BR2_ROOTFS_POST_IMAGE_SCRIPT+ scripts will be passed the arguments filesystem layout and some basic init scripts and configuration files.
specified in +BR2_ROOTFS_POST_SCRIPT_ARGS+ (if that is not empty). +
All the scripts will be passed the exact same set of arguments, it If the default skeleton (available under +system/skeleton+) does not
is not possible to pass different sets of arguments to each script. match your needs, you would typically use a root filesystem overlay or
post-build script to adapt it. However, if the default skeleton is
entirely different than what you need, using a custom skeleton may be
more suitable.
+
To enable this feature, enable config option
+BR2_ROOTFS_SKELETON_CUSTOM+ and set +BR2_ROOTFS_SKELETON_CUSTOM_PATH+
to the path of your custom skeleton. Both options are available in the
+System configuration+ menu. If you specify a relative path, it will
be relative to the root of the Buildroot tree.
+
This method is not recommended because it duplicates the entire
skeleton, which prevents taking advantage of the fixes or improvements
brought to the default skeleton in later Buildroot releases.

2
docs/manual/customize.txt
View File

@ -40,6 +40,8 @@ include::customize-outside-br.txt[]
include::customize-rootfs.txt[] include::customize-rootfs.txt[]
include::customize-post-image.txt[]
include::customize-store.txt[] include::customize-store.txt[]
include::customize-packages.txt[] include::customize-packages.txt[]