From patchwork Sun May 13 10:38:14 2012 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Samuel Martin X-Patchwork-Id: 158818 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from fraxinus.osuosl.org (fraxinus.osuosl.org [140.211.166.137]) by ozlabs.org (Postfix) with ESMTP id CEA5AB7002 for ; Sun, 13 May 2012 20:41:07 +1000 (EST) Received: from localhost (localhost [127.0.0.1]) by fraxinus.osuosl.org (Postfix) with ESMTP id C8B491012D1; Sun, 13 May 2012 10:41:06 +0000 (UTC) X-Virus-Scanned: amavisd-new at osuosl.org Received: from fraxinus.osuosl.org ([127.0.0.1]) by localhost (.osuosl.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id 1S9iQzdOmY9s; Sun, 13 May 2012 10:40:58 +0000 (UTC) Received: from ash.osuosl.org (ash.osuosl.org [140.211.166.34]) by fraxinus.osuosl.org (Postfix) with ESMTP id 7E6EF1013FE; Sun, 13 May 2012 10:40:32 +0000 (UTC) X-Original-To: buildroot@lists.busybox.net Delivered-To: buildroot@osuosl.org Received: from whitealder.osuosl.org (whitealder.osuosl.org [140.211.166.138]) by ash.osuosl.org (Postfix) with ESMTP id C49488F75B for ; Sun, 13 May 2012 10:39:47 +0000 (UTC) Received: from localhost (localhost [127.0.0.1]) by whitealder.osuosl.org (Postfix) with ESMTP id 987F581C2D for ; Sun, 13 May 2012 10:39:47 +0000 (UTC) X-Virus-Scanned: amavisd-new at osuosl.org Received: from whitealder.osuosl.org ([127.0.0.1]) by localhost (.osuosl.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id C-rFznt+SKLo for ; Sun, 13 May 2012 10:39:31 +0000 (UTC) X-Greylist: domain auto-whitelisted by SQLgrey-1.7.6 Received: from mail-wi0-f175.google.com (mail-wi0-f175.google.com [209.85.212.175]) by whitealder.osuosl.org (Postfix) with ESMTPS id 7F249845BD for ; Sun, 13 May 2012 10:39:30 +0000 (UTC) Received: by wibhn6 with SMTP id hn6so1405798wib.10 for ; Sun, 13 May 2012 03:39:28 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=from:to:cc:subject:date:message-id:x-mailer:in-reply-to:references; bh=vgCghg+5EspiPN2QeF90a4oQWY2m84FUecH8fevam78=; b=EAS7boLiTPPLbR1ZwGmVVb2e1TV/eoDaGzuRfUqP/HKAZF1LzO4AKVMEwX8NcJOsJ8 bLMJet5XnpI3pfVdYW6Qreo/wdlWkuZIgAOJo69rUW5fOD7zgvDKVAdLMbW4ytohmTcn mFJhGSeNywzYng6gMCgwJi/OU3fd0QfKbSHeuaNhcmavD7UYkJvVjjk5pEDPsh5jJH9n sj1N/+JkdT1NeSoBUkl01SaTasCeZYfKXeTxKg7EIth5qElpZscInHK/s0X95Qmu4Lpg ELDcilXl38UDbM7ZNwgA7aQ4jX+cdcXb6YL/9qg2aCKYf5IaUs2R59rwdxp1VklIzsH1 t+0w== Received: by 10.180.102.3 with SMTP id fk3mr10701454wib.9.1336905568216; Sun, 13 May 2012 03:39:28 -0700 (PDT) Received: from localhost.localdomain (ivr94-4-82-229-165-48.fbx.proxad.net. [82.229.165.48]) by mx.google.com with ESMTPS id r2sm41271946wif.7.2012.05.13.03.39.26 (version=SSLv3 cipher=OTHER); Sun, 13 May 2012 03:39:27 -0700 (PDT) From: Samuel Martin To: buildroot@busybox.net Date: Sun, 13 May 2012 12:38:14 +0200 Message-Id: <1336905501-9757-5-git-send-email-s.martin49@gmail.com> X-Mailer: git-send-email 1.7.10.2 In-Reply-To: <1336905501-9757-1-git-send-email-s.martin49@gmail.com> References: <4FAEEFA8.2070005@mind.be> <1336905501-9757-1-git-send-email-s.martin49@gmail.com> Subject: [Buildroot] [PATCH v2 04/11] manual: rework using.txt and update common-usage.txt X-BeenThere: buildroot@busybox.net X-Mailman-Version: 2.1.14 Precedence: list List-Id: Discussion and development of buildroot List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: buildroot-bounces@busybox.net Sender: buildroot-bounces@busybox.net From: Samuel MARTIN Consider the second chapter: "starting-up", as a tutorial. Assuming that, using.txt only contains the very first commands used to get configure and build its very first target system. So, the following subsection from using.txt have been to common-usage.txt: - Offline builds - Building out-of-tree - Environment variables Signed-off-by: Samuel Martin diff --git a/docs/manual/common-usage.txt b/docs/manual/common-usage.txt index ff8543f..dde1ab0 100644 --- a/docs/manual/common-usage.txt +++ b/docs/manual/common-usage.txt @@ -2,3 +2,80 @@ Daily use --------- include::rebuilding-packages.txt[] + +Offline builds +~~~~~~~~~~~~~~ + +If you intend to do an offline build and just want to download +all sources that you previously selected in the configurator +('menuconfig', 'xconfig' or 'gconfig'), then issue: + +-------------------- + $ make source +-------------------- + +You can now disconnect or copy the content of your +dl+ +directory to the build-host. + +Building out-of-tree +~~~~~~~~~~~~~~~~~~~~ + +Buildroot supports building out of tree with a syntax similar to the +Linux kernel. To use it, add +O=+ to the make command line: + +-------------------- + $ make O=/tmp/build +-------------------- + +Or: + +-------------------- + $ cd /tmp/build; make O=$PWD -C path/to/buildroot +-------------------- + +All the output files will be located under +/tmp/build+. + +When using out-of-tree builds, the Buildroot +.config+ and temporary +files are also stored in the output directory. This means that you can +safely run multiple builds in parallel using the same source tree as +long as they use unique output directories. + +For ease of use, Buildroot generates a Makefile wrapper in the output +directory - So after the first run, you no longer need to pass +O=..+ +and +-C ..+, simply run (in the output directory): + +-------------------- + $ make +-------------------- + +[[env-vars]] + +Environment variables +~~~~~~~~~~~~~~~~~~~~~ + +Buildroot also honors some environment variables, when they are passed +to +make+ or set in the environment: + +* +HOSTCXX+, the host C++ compiler to use +* +HOSTCC+, the host C compiler to use +* +UCLIBC_CONFIG_FILE=+, path to + the uClibc configuration file, used to compile uClibc, if an + internal toolchain is being built +* +BUSYBOX_CONFIG_FILE=+, path to + the Busybox configuration file +* +BUILDROOT_DL_DIR+ to override the directory in which + Buildroot stores/retrieves downloaded files + +An example that uses config files located in the toplevel directory and +in your $HOME: + +-------------------- + $ make UCLIBC_CONFIG_FILE=uClibc.config BUSYBOX_CONFIG_FILE=$HOME/bb.config +-------------------- + +If you want to use a compiler other than the default +gcc+ +or +g+++ for building helper-binaries on your host, then do + +-------------------- + $ make HOSTCXX=g++-4.3-HEAD HOSTCC=gcc-4.3-HEAD +-------------------- diff --git a/docs/manual/using.txt b/docs/manual/using.txt index 88dc58c..2945098 100644 --- a/docs/manual/using.txt +++ b/docs/manual/using.txt @@ -3,8 +3,8 @@ Using Buildroot Buildroot has a nice configuration tool similar to the one you can find in the http://www.kernel.org/[Linux kernel] or in -http://www.busybox.net/[Busybox]. Note that you can (and should) build -everything as a normal user. There is no need to be root to configure +http://www.busybox.net/[Busybox]. Note that you can *and should build +everything as a normal user*. There is no need to be root to configure and use Buildroot. The first step is to run the configuration assistant: @@ -27,12 +27,11 @@ or to run the Qt or GTK-based configurators. All of these "make" commands will need to build a configuration -utility, so you may need to install "development" packages for -relevant libraries used by the configuration utilities. On Debian-like -systems, the +libncurses5-dev+ package is required to use the -'menuconfig' interface, +libqt4-dev+ is required to use the 'xconfig' -interface, and +libglib2.0-dev, libgtk2.0-dev and libglade2-dev+ are -needed to use the 'gconfig' interface. +utility (including the interface), so you may need to install +"development" packages for relevant libraries used by the +configuration utilities. Check the xref:requirement[] to know what +Buildroot needs, and specifically the xref:requirement-optional[system requirements] +to get the dependencies of favourite interface. For each menu entry in the configuration tool, you can find associated help that describes the purpose of the entry. @@ -54,9 +53,9 @@ tell Buildroot to run each package compilation with +make -jN+. This command will generally perform the following steps: * Download source files (as required) -* Configure, build and install the cross-compiling toolchain if an - internal toolchain is used, or import a toolchain if an external - toolchain is used +* Configure, build and install the cross-compiling toolchain using the + appropiate toolchain backend is used, or simply import a toolchain + if an external toolchain is used * Build/install selected target packages * Build a kernel image, if selected * Build a bootloader image, if selected @@ -103,78 +102,9 @@ This directory contains several subdirectories: * +toolchain/+ contains the build directories for the various components of the cross-compilation toolchain. -Offline builds --------------- +These commands, +make menuconfig|gconfig|xconfig+ and +make+, are the +basic ones that allow to easily and quickly generate images fitting +your needs, with all the supports and applications you enabled. -If you intend to do an offline build and just want to download -all sources that you previously selected in the configurator -('menuconfig', 'xconfig' or 'gconfig'), then issue: - --------------------- - $ make source --------------------- - -You can now disconnect or copy the content of your +dl+ -directory to the build-host. - -Building out-of-tree --------------------- - -Buildroot supports building out of tree with a syntax similar to the -Linux kernel. To use it, add +O=+ to the make command line: - --------------------- - $ make O=/tmp/build --------------------- - -Or: - --------------------- - $ cd /tmp/build; make O=$PWD -C path/to/buildroot --------------------- - -All the output files will be located under +/tmp/build+. - -When using out-of-tree builds, the Buildroot +.config+ and temporary -files are also stored in the output directory. This means that you can -safely run multiple builds in parallel using the same source tree as -long as they use unique output directories. - -For ease of use, Buildroot generates a Makefile wrapper in the output -directory - So after the first run, you no longer need to pass +O=..+ -and +-C ..+, simply run (in the output directory): - --------------------- - $ make --------------------- - -Environment variables ---------------------- -[[env-vars]] - -Buildroot also honors some environment variables, when they are passed -to +make+ or set in the environment: - -* +HOSTCXX+, the host C++ compiler to use -* +HOSTCC+, the host C compiler to use -* +UCLIBC_CONFIG_FILE=+, path to - the uClibc configuration file, used to compile uClibc, if an - internal toolchain is being built -* +BUSYBOX_CONFIG_FILE=+, path to - the Busybox configuration file -* +BUILDROOT_DL_DIR+ to override the directory in which - Buildroot stores/retrieves downloaded files - -An example that uses config files located in the toplevel directory and -in your $HOME: - --------------------- - $ make UCLIBC_CONFIG_FILE=uClibc.config BUSYBOX_CONFIG_FILE=$HOME/bb.config --------------------- - -If you want to use a compiler other than the default +gcc+ -or +g+++ for building helper-binaries on your host, then do - --------------------- - $ make HOSTCXX=g++-4.3-HEAD HOSTCC=gcc-4.3-HEAD --------------------- +More details about the "make" command usages are given in +xref:make-tips[].