[OE-core] [PATCH RFC] local.conf.sample: Cleanup and improve

[Khem Raj]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On 08/11/2011 04:39 PM, Richard Purdie wrote:
> local.conf is the first thing anyone 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).
> 
> This is an RFC, I've run out of time this evening to work all the
> way through the file but I thought I'd throw this patch out there as
> it stands and take feedback on whether people feel this is the right
> thing to do. At present I'm assuming we'd do this for OE-Core and
> Yocto, if people feel its Yocto specific I can live with that too.
> The patch is currently Poky based since that is what I had handy at
> the time I tried to add the documentation of DL_DIR which triggered
> this.
> 
> Cheers,
> 
> Richard
> 
> 
> 
> diff --git a/meta-yocto/conf/local.conf.sample
> b/meta-yocto/conf/local.conf.sample index 80ee7b2..9b47c51 100644 ---
> a/meta-yocto/conf/local.conf.sample +++
> b/meta-yocto/conf/local.conf.sample @@ -1,37 +1,96 @@ -# 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"

I guess those machines will need some extra layers. It would not apply
to oe-core only. So either its documented how to enable them or safely
remove them

> +# +# 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"
> 
> DISTRO ?= "poky" # For bleeding edge / experimental / unstable
> package versions @@ -64,86 +123,16 @@ EXTRA_IMAGE_FEATURES =
> "debug-tweaks" # 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" +PACKAGE_CLASSES ?= "package_rpm"

I guess documenting what other options are available would be nice
like it was above.

> 
> # 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 +# NOTE: mklibs also needs to be explicitly
> enabled for a given image, see local.conf.extended 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. -# -#
> 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. @@ -159,72 +148,38 @@ BBINCLUDELOGS = "yes" #file://.*
> http://someserver.tld/share/sstate/ \n \ #file://.*
> file:///some/local/dir/sstate/"
> 
> -# Set IMAGETEST to qemu if you want to build testcases and start -#
> testing in qemu after do_rootfs. +# Uncomment this if you wish to
> test booting virtual machine images under qemu +# (an emulator) after
> any root filesystems are created and run tests against +# those
> images #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 +#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 much time. +#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" - # 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 +#
> when resolving patches which cannot be applied or to use devshell +#
> or the kernel menuconfig # 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 by setting (tasks will just fail instead): 
> #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" - -# 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 277ee2a..a31dc3d
> 100644 --- a/meta-yocto/conf/local.conf.sample.extended +++
> b/meta-yocto/conf/local.conf.sample.extended @@ -10,3 +10,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" diff --git a/meta/conf/distro/include/default-distrovars.inc
> b/meta/conf/distro/include/default-distrovars.inc index
> 2ef25e4..c2fd77e 100644 ---
> a/meta/conf/distro/include/default-distrovars.inc +++
> b/meta/conf/distro/include/default-distrovars.inc @@ -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" +
> 
> 
> _______________________________________________ Openembedded-core
> mailing list Openembedded-core at lists.openembedded.org 
> http://lists.linuxtogo.org/cgi-bin/mailman/listinfo/openembedded-core
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.11 (GNU/Linux)

iEUEARECAAYFAk5ExWAACgkQuwUzVZGdMxSTcACghcYwY6UJeQnsSsuOIv/YpSYX
3bYAlicY9O8j9YFc/rYeesQSjJqgpP0=
=h6dY
-----END PGP SIGNATURE-----