From b85957b011afc163b7e9930e83adbfb922ddfae8 Mon Sep 17 00:00:00 2001 From: Richard Purdie Date: Fri, 12 Aug 2011 00:30:22 +0100 Subject: local.conf.sample: Cleanup and improve local.conf is the first thing anyone new to the project sees. Over time it has built up a ton cruft and isn't even accurate in places. This patch: * Moves things to local.conf.sample.extended if a new user is unlikely to need to immediately care about the options * Reorders the file to be more intuitive to a new user * Moves certain default values to default-distrovars.inc in cases where most users wouldn't want to change the value * Adds large blocks of text to explain what an option does. There have been too many cases of a user not realising what some of these settings do and how they can use them to their advantage (like DL_DIR for example). (From OE-Core rev: a0ccb33ac5a2231c979c3369159f763dff1e0a2e) Signed-off-by: Richard Purdie --- meta-yocto/conf/local.conf.sample | 367 ++++++++++++++--------------- meta-yocto/conf/local.conf.sample.extended | 104 ++++++++ 2 files changed, 287 insertions(+), 184 deletions(-) (limited to 'meta-yocto') diff --git a/meta-yocto/conf/local.conf.sample b/meta-yocto/conf/local.conf.sample index 80ee7b2615..644d548f20 100644 --- a/meta-yocto/conf/local.conf.sample +++ b/meta-yocto/conf/local.conf.sample @@ -1,230 +1,229 @@ -# CONF_VERSION is increased each time build/conf/ changes incompatibly -CONF_VERSION = "1" - -# Uncomment and change to cache the files Poky downloads in an alternative -# location, default is ${TOPDIR}/downloads -#DL_DIR ?= "${TOPDIR}/downloads" -# Uncomment and change to cache Poky's built staging output in an alternative -# location, default is ${TOPDIR}/sstate-cache -#SSTATE_DIR ?= "${TOPDIR}/sstate-cache" +# +# This file is your local configuration file and is where all local user settings +# are placed. The comments in this file give some guide to the options a new user +# to the system might want to change but pretty much any configuration option can +# be set in this file. More adventurous users can look at local.conf.extended +# which contains other examples of configuration which can be placed in this file +# but new users likely don't need any of them initially. +# +# Lines starting with the '#' character are commented out and in some cases the +# default values are provided as comments to show people example syntax. Enabling +# the option is a question of removing the # character and making any change to the +# variable as required. -# Uncomment and set to allow bitbake to execute multiple tasks at once. -# For a quadcore, BB_NUMBER_THREADS = "4", PARALLEL_MAKE = "-j 4" would -# be appropriate. -# BB_NUMBER_THREADS = "4" -# Also, make can be passed flags so it run parallel threads e.g.: +# +# Parallelism Options +# +# These two options control how much parallelism BitBake should use. The first +# option determines how many tasks bitbake should run in parallel: +# +#BB_NUMBER_THREADS = "4" +# +# The second option controls how many processes make should run in parallel when +# running compile tasks: +# # PARALLEL_MAKE = "-j 4" +# +# For a quadcore, BB_NUMBER_THREADS = "4", PARALLEL_MAKE = "-j 4" would +# be appropriate for example. -# Set a default machine to target unless a machine is selected from the -# lists below. -MACHINE ??= "qemux86" - -# Supported emulation machines +# +# Machine Selection +# +# You need to select a specific machine to target the build with. There are a selection +# emulated machines available which can boot and run in the QEMU emulator: +# #MACHINE ?= "qemuarm" #MACHINE ?= "qemumips" #MACHINE ?= "qemuppc" #MACHINE ?= "qemux86" #MACHINE ?= "qemux86-64" - -# Supported target hardware for demonstration purposes +# +# There are also the following hardware board target machines included for +# demonstration purposes: +# #MACHINE ?= "atom-pc" #MACHINE ?= "beagleboard" #MACHINE ?= "emenlow" #MACHINE ?= "mpc8315e-rdb" #MACHINE ?= "routerstationpro" +# +# This sets the default machine to be qemux86 if no other machine is selected: +MACHINE ??= "qemux86" -DISTRO ?= "poky" -# For bleeding edge / experimental / unstable package versions -# DISTRO ?= "poky-bleeding" - -# BBMASK is a regular expression that can be used to tell BitBake to ignore -# certain recipes. -#BBMASK = "" - -# EXTRA_IMAGE_FEATURES allows extra packages to be added to the generated images -# (Some of these are automatically added to certain image types) -# "dbg-pkgs" - add -dbg packages for all installed packages -# (adds symbol information for debugging/profiling) -# "dev-pkgs" - add -dev packages for all installed packages -# (useful if you want to develop against libs in the image) -# "tools-sdk" - add development tools (gcc, make, pkgconfig etc.) -# "tools-debug" - add debugging tools (gdb, strace) -# "tools-profile" - add profiling tools (oprofile, exmap, lttng valgrind (x86 only)) -# "tools-testapps" - add useful testing tools (ts_print, aplay, arecord etc.) -# "debug-tweaks" - make an image for suitable of development -# e.g. ssh root access has a blank password -# There are other application targets too, see meta/classes/core-image.bbclass -# and meta/recipes-core/tasks/task-core.bb for more details. -# The -sdk image includes these features by default now. -EXTRA_IMAGE_FEATURES = "debug-tweaks" - -# A list of packaging systems used in generated images -# The first package type listed will be used for rootfs generation -# include 'package_deb' for debs -# include 'package_ipk' for ipks -# include 'package_rpm' for rpms -#PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk" -PACKAGE_CLASSES ?= "package_rpm package_ipk" - -# mklibs library size optimization is more useful to smaller images, -# and less useful for bigger images. Also mklibs library optimization -# can break the ABI compatibility, so should not be applied to the -# images which are to be extended or upgraded later. -#This enabled mklibs library size optimization just for the specified image. -#MKLIBS_OPTIMIZED_IMAGES ?= "core-image-minimal" -#This enable mklibs library size optimization will be for all the images. -#MKLIBS_OPTIMIZED_IMAGES ?= "all" - -# A list of additional classes to use when building the system -# include 'image-mklibs' to reduce shared library files size for an image -# include 'image-prelink' in order to prelink the filesystem image -# include 'image-swab' to perform host system intrusion detection -# NOTE: if listing mklibs & prelink both, then make sure mklibs is before prelink -USER_CLASSES ?= "image-mklibs image-prelink" - -# POKYMODE controls the characteristics of the generated packages/images by -# telling poky which type of toolchain to use. # -# Options include several different EABI combinations and a compatibility -# mode for the OABI mode poky previously used. +# Where to place downloads # -# The default is "eabi" -# Use "oabi" for machines with kernels < 2.6.18 on ARM for example. -# Use "external-MODE" to use the precompiled external toolchains where MODE -# is the type of external toolchain to use e.g. eabi. -# POKYMODE = "external-eabi" - -# Uncomment this to specify where BitBake should create its temporary files. -# Note that a full build of everything in OpenEmbedded will take GigaBytes of hard -# disk space, so make sure to free enough space. The default TMPDIR is -# /tmp -#TMPDIR = "${COREBASE}/build/tmp" +# During a first build the system will download many differernt source code tarballs +# from various upstream projects. This can take a while, particularly if your network +# connection is slow. These are all stored in DL_DIR. When wiping and rebuilding you +# can preserve this directory to speed up this part of subsequent builds. This directory +# is safe to share between multiple builds on the same machine too. +# +# The default is a downloads directory under TOPDIR which is the build directory. +# +#DL_DIR ?= "${TOPDIR}/downloads" -# The following are used to control options related to debugging. # -# Uncomment this to change the optimization to make debugging easer, at the -# possible cost of performance. -# DEBUG_BUILD = "1" +# Where to place shared-state files +# +# BitBake has the capability to accelerate builds based on previously built output. +# This is done using "shared state" files which can be through of as cache objects +# and this option determines where those files are placed. # -# Uncomment this to disable the stripping of the installed binaries -# INHIBIT_PACKAGE_STRIP = "1" +# You can wipe out TMPDIR leaving this directory intact and the build would regenerate +# from these files if no chages were made to the configuration. If changes were made +# to the configuration, only shared state files where the state was still valid would +# be used (done using checksums). # -# Uncomment this to disable the split of the debug information into -dbg files -# INHIBIT_PACKAGE_DEBUG_SPLIT = "1" +# The default is a sstate-cache directory under TOPDIR. # -# When splitting debug information, the following controls the results of the -# file splitting. +#SSTATE_DIR ?= "${TOPDIR}/sstate-cache" + # -# .debug (default): -# When splitting the debug information will be placed into -# a .debug directory in the same dirname of the binary produced: -# /bin/foo -> /bin/.debug/foo +# Where to place the build output # -# debug-file-directory: -# When splitting the debug information will be placed into -# a central debug-file-directory, /usr/lib/debug: -# /bin/foo -> /usr/lib/debug/bin/foo.debug +# This option specifies where the bulk of the building work should be done and +# where BitBake should place its temporary files and output. Keep in mind that +# this includes the extraction and complation of many applications and the toolchain +# which can use Gigabytes of hard disk space. # -# Any source code referenced in the debug symbols will be copied -# and made available within the /usr/src/debug directory +# The default is a tmp directory under TOPDIR. # -PACKAGE_DEBUG_SPLIT_STYLE = '.debug' -# PACKAGE_DEBUG_SPLIT_STYLE = 'debug-file-directory' +#TMPDIR = "${TOPDIR}/tmp" -# Uncomment these to build a package such that you can use gprof to profile it. -# NOTE: This will only work with 'linux' targets, not -# 'linux-uclibc', as uClibc doesn't provide the necessary -# object files. Also, don't build glibc itself with these -# flags, or it'll fail to build. -# -# PROFILE_OPTIMIZATION = "-pg" -# SELECTED_OPTIMIZATION = "${PROFILE_OPTIMIZATION}" -# LDFLAGS =+ "-pg" +# +# Default policy config +# +# The distribution setting controls which policy settings are used as defaults. +# The default value is fine for general Yocto project use, at least initially. +# Ultimately when creating custom policy, people will likely end up subclassing +# these defaults. +# +DISTRO ?= "poky" +# As an exable of a subclass there is a "bleeding" egde policy configuration +# where many versions are set to the absolute latest code from the upstream +# source control systems. This is just mentioned here an an example, its not +# useful to most new users. +# DISTRO ?= "poky-bleeding" -# Uncomment this if you want BitBake to emit the log if a build fails. -BBINCLUDELOGS = "yes" +# +# Package Management configuration +# +# This variable lists which packaging formats to enable. Multiple package backends +# can be enabled at once and the first item listed in the variable will be used +# to generate the root filesystems. +# Options are: +# - 'package_deb' for debian style deb files +# - 'package_ipk' for ipk files are used by opkg (a debian style embedded package manager) +# - 'package_rpm' for rpm style packages +# E.g.: PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk" +# We default to rpm: +PACKAGE_CLASSES ?= "package_rpm" -# The architecture to build SDK items for, by setting this you can build SDK -# packages for architectures other than the host i.e. building i686 packages -# on an x86_64 host. +# +# SDK/ADT target architecture +# +# This variable specified the architecture to build SDK/ADT items for and means +# you can build the SDK packages for architectures other than the machine you are +# running the build on (i.e. building i686 packages on an x86_64 host._ # Supported values are i686 and x86_64 #SDKMACHINE ?= "i686" -# The build system can check data caches for prebuilt data objects before -# it builds the data itself. This can be a filesystem directory, or a remote url -# such as http or ftp. These would contain the sstate-cache results from previous -# builds (possibly from other machines). This variable works like fetcher -# MIRRORS/PREMIRRORS and points to the cache locations to check for the shared objects. -#SSTATE_MIRRORS ?= "\ -#file://.* http://someserver.tld/share/sstate/ \n \ -#file://.* file:///some/local/dir/sstate/" +# +# Extra image configuration defaults +# +# The EXTRA_IMAGE_FEATURES variable allows extra packages to be added to the generated +# images. Some of these options are added to certain image types automatically. The +# variable can contain the following options: +# "dbg-pkgs" - add -dbg packages for all installed packages +# (adds symbol information for debugging/profiling) +# "dev-pkgs" - add -dev packages for all installed packages +# (useful if you want to develop against libs in the image) +# "tools-sdk" - add development tools (gcc, make, pkgconfig etc.) +# "tools-debug" - add debugging tools (gdb, strace) +# "tools-profile" - add profiling tools (oprofile, exmap, lttng valgrind (x86 only)) +# "tools-testapps" - add useful testing tools (ts_print, aplay, arecord etc.) +# "debug-tweaks" - make an image for suitable of development +# e.g. ssh root access has a blank password +# There are other application targets that can be uses here too, see +# meta/classes/core-image.bbclass and meta/recipes-core/tasks/task-core.bb for more details. +# We default to enabling the debugging tweaks. +EXTRA_IMAGE_FEATURES = "debug-tweaks" -# Set IMAGETEST to qemu if you want to build testcases and start -# testing in qemu after do_rootfs. -#IMAGETEST = "qemu" +# +# Additional image features +# +# The following is a list of additional classes to use when building images which +# enable extra features. Some available options which can be included in this variable +# are: +# - 'image-mklibs' to reduce shared library files size for an image +# - 'image-prelink' in order to prelink the filesystem image +# - 'image-swab' to perform host system intrusion detection +# NOTE: if listing mklibs & prelink both, then make sure mklibs is before prelink +# NOTE: mklibs also needs to be explicitly enabled for a given image, see local.conf.extended +USER_CLASSES ?= "image-mklibs image-prelink" -# By default test cases in sanity suite will be ran. If you want to run other -# test suite or specific test case(e.g. bat or boot test case under sanity suite), -# list them like following. +# +# Runtime testing of images +# +# The build system can test booting virtual machine images under qemu (an emulator) +# after any root filesystems are created and run tests against those images. To +# enable this uncomment this line +#IMAGETEST = "qemu" +# +# This variable controls which tests are run against virtual images if enabled +# above. The following would enable bat, oot test case under sanity suite and +# toolchain tests #TEST_SCEN = "sanity bat sanity:boot toolchain" - -#Because of the QEMU booting slowness issue(see bug #646 and #618), autobuilder -#may suffer a timeout issue when running sanity test. We introduce variable -#TEST_SERIALIZE here to reduce the time on sanity test. It is by default set -#to 1. Poky will start image and run cases in the same image without reboot -#or kill. If it is set to 0, the image will be copied and tested for each -#case, which will take much time. +# +# Because of the QEMU booting slowness issue(see bug #646 and #618), autobuilder +# may suffer a timeout issue when running sanity test. We introduce variable +# TEST_SERIALIZE here to reduce the time on sanity test. It is by default set +# to 1. This will start image and run cases in the same image without reboot +# or kill. If it is set to 0, the image will be copied and tested for each +# case, which will take longer but be more precise. #TEST_SERIALIZE = "1" -# ENABLE_BINARY_LOCALE_GENERATION controls the generation of binary locale -# packages at build time using qemu-native. Disabling it (by setting it to 0) -# will save some build time at the expense of breaking i18n on devices with -# less than 128MB RAM. -ENABLE_BINARY_LOCALE_GENERATION = "1" - -# Set GLIBC_GENERATE_LOCALES to the locales you wish to generate should you not -# wish to perform the time-consuming step of generating all LIBC locales. -# NOTE: If removing en_US.UTF-8 you will also need to uncomment, and set -# appropriate values for IMAGE_LINGUAS and LIMIT_BUILT_LOCALES -# WARNING: this may break localisation! -#GLIBC_GENERATE_LOCALES = "en_GB.UTF-8 en_US.UTF-8" -# See message above as to whether setting these is required -#IMAGE_LINGUAS ?= "en-gb" -#LIMIT_BUILT_LOCALES ?= "POSIX en_GB" - -# This value is currently used by pseudo to determine if the recipe should -# build both the 32-bit and 64-bit wrapper libraries on a 64-bit build system. -# -# Pseudo will attempt to determine if a 32-bit wrapper is necessary, but -# it doesn't always guess properly. If you have 32-bit executables on -# your 64-bit build system, you likely want to set this to "0", -# otherwise you could end up with incorrect file attributes on the -# target filesystem. -# -# Default to not build 32 bit libs on 64 bit systems, comment this -# out if that is desired -NO32LIBS = "1" - +# +# Interactive shell configuration +# +# Under certain circumstances the system may need input from you and to do this it +# can launch an interactive shell. It needs to do this since the build is +# multithreaded and needs to be able to handle the case where more than one parallel +# process may require the user's attention. The default is to use xterm. +# +# Examples of the occasions this may happen are when resolving patches which cannot +# be applied, to use the devshell or the kernel menuconfig +# # If you do not use (or have installed) xterm you will need to # uncomment these variables and set them to the terminal you wish to use -# when resolving patches which cannot be applied -# Supported shell prefixes for *_TERMCMD and *_TERMCMDRUN ARE: +# +# Supported shell prefixes for *_TERMCMD and *_TERMCMDRUN are: # GNOME, SCREEN, XTERM and KONSOLE # Note: currently, Konsole support only works for KDE 3.x due to the way # newer Konsole versions behave #TERMCMD = "${XTERM_TERMCMD}" #TERMCMDRUN = "${XTERM_TERMCMDRUN}" -# Alternatively, if you prefer you can disable patch resolution: +# You can disable interactive patch resolution (tasks will just fail instead) with: #PATCHRESOLVE = "noop" -# The network based PR service host and port -#PRSERV_HOST = "localhost" -#PRSERV_PORT = "8585" - -# Uncomment this if your host distribution provides the help2man tool. -#ASSUME_PROVIDED += "help2man-native" +# +# Shared-state files from other locations +# +# As mentioned above, shared state files are prebuilt cache data objects which can +# used to accelerate build time. This variable can be used to configure the system +# to search other mirror locations for these objects before it builds the data itself. +# +# This can be a filesystem directory, or a remote url such as http or ftp. These +# would contain the sstate-cache results from previous builds (possibly from other +# machines). This variable works like fetcher MIRRORS/PREMIRRORS and points to the +# cache locations to check for the shared objects. +#SSTATE_MIRRORS ?= "\ +#file://.* http://someserver.tld/share/sstate/ \n \ +#file://.* file:///some/local/dir/sstate/" -# Uncomment the following lines to enable multilib builds -#require conf/multilib.conf -#MULTILIBS = "multilib:lib32" -#DEFAULTTUNE_virtclass-multilib-lib32 = "x86" +# CONF_VERSION is increased each time build/conf/ changes incompatibly and is used to +# track the version of this file when it was generated. This can safely be ignored if +# this doesn't mean anything to you. +CONF_VERSION = "1" diff --git a/meta-yocto/conf/local.conf.sample.extended b/meta-yocto/conf/local.conf.sample.extended index 277ee2a8ec..a42774cfac 100644 --- a/meta-yocto/conf/local.conf.sample.extended +++ b/meta-yocto/conf/local.conf.sample.extended @@ -1,3 +1,7 @@ +# BBMASK is a regular expression that can be used to tell BitBake to ignore +# certain recipes. +#BBMASK = "" + # eglibc configurability is used to reduce minimal images's size. # the all supported eglibc options are listed in DISTRO_FEATURES_LIBC # and disabled by default. Uncomment and copy the DISTRO_FEATURES_LIBC @@ -10,3 +14,103 @@ # libc-posix-wchar-io" #DISTRO_FEATURES = "alsa bluetooth ext2 irda pcmcia usbgadget usbhost wifi nfs zeroconf pci ${DISTRO_FEATURES_LIBC}" + +# ENABLE_BINARY_LOCALE_GENERATION controls the generation of binary locale +# packages at build time using qemu-native. Disabling it (by setting it to 0) +# will save some build time at the expense of breaking i18n on devices with +# less than 128MB RAM. +#ENABLE_BINARY_LOCALE_GENERATION = "1" + +# Set GLIBC_GENERATE_LOCALES to the locales you wish to generate should you not +# wish to perform the time-consuming step of generating all LIBC locales. +# NOTE: If removing en_US.UTF-8 you will also need to uncomment, and set +# appropriate values for IMAGE_LINGUAS and LIMIT_BUILT_LOCALES +# WARNING: this may break localisation! +#GLIBC_GENERATE_LOCALES = "en_GB.UTF-8 en_US.UTF-8" +# See message above as to whether setting these is required +#IMAGE_LINGUAS ?= "en-gb" +#LIMIT_BUILT_LOCALES ?= "POSIX en_GB" + +# The following are used to control options related to debugging. +# +# Uncomment this to change the optimization to make debugging easer, at the +# possible cost of performance. +# DEBUG_BUILD = "1" +# +# Uncomment this to disable the stripping of the installed binaries +# INHIBIT_PACKAGE_STRIP = "1" +# +# Uncomment this to disable the split of the debug information into -dbg files +# INHIBIT_PACKAGE_DEBUG_SPLIT = "1" +# +# When splitting debug information, the following controls the results of the +# file splitting. +# +# .debug (default): +# When splitting the debug information will be placed into +# a .debug directory in the same dirname of the binary produced: +# /bin/foo -> /bin/.debug/foo +# +# debug-file-directory: +# When splitting the debug information will be placed into +# a central debug-file-directory, /usr/lib/debug: +# /bin/foo -> /usr/lib/debug/bin/foo.debug +# +# Any source code referenced in the debug symbols will be copied +# and made available within the /usr/src/debug directory +# +#PACKAGE_DEBUG_SPLIT_STYLE = '.debug' +# PACKAGE_DEBUG_SPLIT_STYLE = 'debug-file-directory' + +# Uncomment these to build a package such that you can use gprof to profile it. +# NOTE: This will only work with 'linux' targets, not +# 'linux-uclibc', as uClibc doesn't provide the necessary +# object files. Also, don't build glibc itself with these +# flags, or it'll fail to build. +# +# PROFILE_OPTIMIZATION = "-pg" +# SELECTED_OPTIMIZATION = "${PROFILE_OPTIMIZATION}" +# LDFLAGS =+ "-pg" + +# TCMODE controls the characteristics of the generated packages/images by +# telling poky which toolchain 'profile' to use. +# +# The default is "default" +# Use "external-MODE" to use the precompiled external toolchains where MODE +# is the type of external toolchain to use e.g. eabi. You need to ensure +# the toolchain you want to use is included in an an appropriate layer +# TCMODE = "external-eabi" + +# mklibs library size optimization is more useful to smaller images, +# and less useful for bigger images. Also mklibs library optimization +# can break the ABI compatibility, so should not be applied to the +# images which are to be extended or upgraded later. +#This enabled mklibs library size optimization just for the specified image. +#MKLIBS_OPTIMIZED_IMAGES ?= "core-image-minimal" +#This enable mklibs library size optimization will be for all the images. +#MKLIBS_OPTIMIZED_IMAGES ?= "all" + +# Uncomment this if your host distribution provides the help2man tool. +#ASSUME_PROVIDED += "help2man-native" + +# This value is currently used by pseudo to determine if the recipe should +# build both the 32-bit and 64-bit wrapper libraries on a 64-bit build system. +# +# Pseudo will attempt to determine if a 32-bit wrapper is necessary, but +# it doesn't always guess properly. If you have 32-bit executables on +# your 64-bit build system, you likely want to set this to "0", +# otherwise you could end up with incorrect file attributes on the +# target filesystem. +# +# Default is to not build 32 bit libs on 64 bit systems, uncomment this +# if you need the 32 bits libs +#NO32LIBS = "0" + +# Uncomment the following lines to enable multilib builds +#require conf/multilib.conf +#MULTILIBS = "multilib:lib32" +#DEFAULTTUNE_virtclass-multilib-lib32 = "x86" + +# The network based PR service host and port +#PRSERV_HOST = "localhost" +#PRSERV_PORT = "8585" -- cgit v1.2.3-54-g00ecf