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 <richard.purdie@linuxfoundation.org>
This commit is contained in:
Richard Purdie 2011-08-12 00:30:22 +01:00
parent d31d5e5b34
commit b85957b011
3 changed files with 299 additions and 190 deletions

View File

@ -1,230 +1,229 @@
# CONF_VERSION is increased each time build/conf/ changes incompatibly
CONF_VERSION = "1"
#
# 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 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"
# 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"
#
# Where to place downloads
#
# 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"
#
# 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.
#
# 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).
#
# The default is a sstate-cache directory under TOPDIR.
#
#SSTATE_DIR ?= "${TOPDIR}/sstate-cache"
#
# Where to place the build output
#
# 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.
#
# The default is a tmp directory under TOPDIR.
#
#TMPDIR = "${TOPDIR}/tmp"
#
# 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"
# For bleeding edge / experimental / unstable package versions
# 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"
# BBMASK is a regular expression that can be used to tell BitBake to ignore
# certain recipes.
#BBMASK = ""
#
# 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"
# 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.
# SDK/ADT target architecture
#
# 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
# <build directory>/tmp
#TMPDIR = "${COREBASE}/build/tmp"
# 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"
# Uncomment this if you want BitBake to emit the log if a build fails.
BBINCLUDELOGS = "yes"
# 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.
# 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.
#
# 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"
#
# 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"
# 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.
#
# 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.
# 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
#
# Default to not build 32 bit libs on 64 bit systems, comment this
# out if that is desired
NO32LIBS = "1"
# 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"
#
# 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 this if your host distribution provides the help2man tool.
#ASSUME_PROVIDED += "help2man-native"
# 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"

View File

@ -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"

View File

@ -41,3 +41,9 @@ COMMERCIAL_QT ?= ""
COMMON_LICENSE_DIR ??= "${COREBASE}/meta/files/common-licenses"
BB_GENERATE_MIRROR_TARBALLS ??= "0"
NO32LIBS ??= "1"
# Default to emitting logfiles if a build fails.
BBINCLUDELOGS ??= "yes"