mirrors/poky
1
0
Fork 0
mirror of https://git.yoctoproject.org/poky synced 2026-09-14 21:49:33 +02:00
Code Issues Packages Projects Releases Wiki Activity

toaster-manual: Applied final review edits.

Browse Source 
This should be it unless there are late coming comments.

(From yocto-docs rev: cb32e3330a6fe2d26425f8765689749afcd989e9)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Scott Rifenbark
2015-04-01 14:45:56 -07:00
committed by Richard Purdie
parent faf19c5274
commit d1df6afab2
3 changed files with 113 additions and 98 deletions
Download Patch File Download Diff File Expand all files Collapse all files

90
documentation/toaster-manual/toaster-manual-reference.xml
View File

@@ -12,19 +12,18 @@
This final chapter provides conceptual information on layer sources, This final chapter provides conceptual information on layer sources,
releases, and JSON configuration files. releases, and JSON configuration files.
Also provided is a quick look at some useful Also provided is a quick look at some useful
<filename>manage.py</filename> commands. <filename>manage.py</filename> commands that are Toaster-specific.
Information on <filename>manage.py</filename> commands does exist Information on <filename>manage.py</filename> commands does exist
across the Web and the information in this manual by no means across the Web and the information in this manual by no means
attempts to provide a command reference. attempts to provide a command comprehensive reference.
However, having relevant command useful for the Toaster context
is helpful.
</para> </para>
<section id='layer-source'> <section id='layer-source'>
<title>Layer Source</title> <title>Layer Source</title>
<para> <para>
In general, a layer source is some source of existing layers. In general, a "layer source" is a source of information about
existing layers.
In particular, we are concerned with layers that you can use In particular, we are concerned with layers that you can use
with the Yocto Project and Toaster. with the Yocto Project and Toaster.
This chapter describes a particular type of layer source called This chapter describes a particular type of layer source called
@@ -145,7 +144,7 @@
</section> </section>
<section id='select-the-toasterconf-json-file'> <section id='select-the-toasterconf-json-file'>
<title>Select the <filename>toasterconf.json</filename> File</title> <title>Select for Use the <filename>toasterconf.json</filename> File</title>
<para> <para>
If you do not want to use the Administration If you do not want to use the Administration
@@ -155,8 +154,8 @@
</para> </para>
<para> <para>
When you set up Toaster in Build Mode, you are prompted to When you set up Toaster in Build Mode, you are prompted
select a Toaster configuration file. to select a Toaster configuration file.
This configuration file is used to set up the initial This configuration file is used to set up the initial
configuration values within the Toaster database configuration values within the Toaster database
including the layer sources. including the layer sources.
@@ -309,9 +308,8 @@
$ bitbake/lib/toaster/manage.py loadconf /home/scottrif/poky/meta-yocto/conf/toasterconf.json $ bitbake/lib/toaster/manage.py loadconf /home/scottrif/poky/meta-yocto/conf/toasterconf.json
</literallayout> </literallayout>
After entering this command, you need to update the After entering this command, you need to update the
information from the layer index to populate the Toaster database with the information coming from your
Toaster database with the information from your layer new layer source.
index.
To do that, you should run the To do that, you should run the
"<filename>lsupdates</filename>" command from the directory "<filename>lsupdates</filename>" command from the directory
that contains the Toaster database. that contains the Toaster database.
@@ -329,7 +327,7 @@
information is available by using the Toaster web interface. information is available by using the Toaster web interface.
To do that, visit the "All compatible layers" page inside a To do that, visit the "All compatible layers" page inside a
Toaster project. Toaster project.
The layers from your layer index should be listed there. The layers from your layer source should be listed there.
</para> </para>
</section> </section>
</section> </section>
@@ -340,6 +338,8 @@
<title>Releases</title> <title>Releases</title>
<para> <para>
When you create a Toaster project using the web interface,
you are asked to choose a "Release."
In the context of Toaster, the term "Release" refers to a set of In the context of Toaster, the term "Release" refers to a set of
layers and a BitBake version the OpenEmbedded build system uses layers and a BitBake version the OpenEmbedded build system uses
to build something. to build something.
@@ -347,8 +347,6 @@
correspond to Yocto Project release branches. correspond to Yocto Project release branches.
However, you can modify, delete, and create new releases However, you can modify, delete, and create new releases
according to your needs. according to your needs.
When you create a Toaster project using the web interface,
you are asked to choose a "Release."
This section provides some background information on releases. This section provides some background information on releases.
</para> </para>
@@ -461,7 +459,7 @@
This name is never exposed through Toaster. This name is never exposed through Toaster.
</para></listitem> </para></listitem>
<listitem><para><emphasis>Git URL:</emphasis> <listitem><para><emphasis>Git URL:</emphasis>
The URL <filename>giturl</filename> The URL (<filename>giturl</filename>)
for the BitBake Git repository cloned for the BitBake Git repository cloned
for Toaster projects. for Toaster projects.
</para></listitem> </para></listitem>
@@ -493,9 +491,6 @@
(<filename>defaultlayers</filename>) automatically (<filename>defaultlayers</filename>) automatically
added to the project configuration when a project is added to the project configuration when a project is
created. created.
You can download the recommended configuration
for this case from
<ulink url='&YOCTO_WIKI_URL;/wiki/File:Toasterconf.json.txt.patch'></ulink>.
</para></listitem> </para></listitem>
<listitem><para><emphasis>Layer Source Priorities</emphasis> <listitem><para><emphasis>Layer Source Priorities</emphasis>
A specification of A specification of
@@ -522,9 +517,11 @@
<para> <para>
To summarize what comprises a release, consider the following To summarize what comprises a release, consider the following
example from a Toaster JSON file. example from a Toaster JSON file.
The configuration names the release "master" and sets it to The configuration names the release "master" and uses the
use the master branch of the "master" branch provided by the layer source of type
<filename>openembedded-core</filename> layer. "layerindex", which is called "OpenEmbedded", and sets
the <filename>openembedded-core</filename> layer as the one
to be added by default to any projects created in Toaster.
The BitBake version used would be defined as shown earlier The BitBake version used would be defined as shown earlier
in the previous list: in the previous list:
<literallayout class='monospaced'> <literallayout class='monospaced'>
@@ -548,13 +545,13 @@
<title>JSON Files</title> <title>JSON Files</title>
<para> <para>
If you are going to be using the Toaster in Build Mode, it must If you are going to be using Toaster in Build Mode, it must
be initially configured before use. be initially configured before use.
Configuration customizes layer source settings and Toaster defaults Configuration customizes layer source settings and Toaster defaults
for all users and is performed by the person responsible for for all users and is performed by the person responsible for
Toaster Configuration (i.e the Toaster Administrator). Toaster Configuration (i.e the Toaster Administrator).
The Toaster Administrator performs this configuration through the The Toaster Administrator performs this configuration through the
admin web interface. Django administration interface.
</para> </para>
<para> <para>
@@ -575,10 +572,10 @@
<filename>toasterconf.json</filename>. <filename>toasterconf.json</filename>.
The Toaster Administrator can customize the file prior to loading The Toaster Administrator can customize the file prior to loading
it into Toaster. it into Toaster.
In the Local Toaster Build Mode, the system startup script When you set up Toaster locally to run in Build Mode, the system
actively looks for compatible configuration files and prompts startup script actively looks for compatible configuration files
you to select a file to load if it detects that the database has and prompts you to select a file to load if it detects that the
not been configured. database has not been configured.
</para> </para>
<section id='json-file-choices'> <section id='json-file-choices'>
@@ -630,7 +627,7 @@
<para> <para>
The <filename>toasterconf.json</filename> file consists of The <filename>toasterconf.json</filename> file consists of
easily readable areas: configuration, layer sources, BitBake, easily readable areas: configuration, layer sources, BitBake,
default, and releases. default release, and releases.
</para> </para>
<section id='json-config-area'> <section id='json-config-area'>
@@ -760,8 +757,13 @@
<para> <para>
This area of the JSON file defines the version of This area of the JSON file defines the version of
BitBake Toaster uses. BitBake Toaster uses.
As shipped, Toaster is configured to recognize three As shipped, Toaster is configured to recognize four
versions of BitBake: master, dizzy, and HEAD. versions of BitBake: master, dizzy, and HEAD.
<note>
HEAD is a special option that builds whatever is
available on disk, without checking out any remote
Git repositories.
</note>
</para> </para>
<para> <para>
@@ -937,14 +939,16 @@
using the using the
<link linkend='toaster-command-builddelete'><filename>builddelete</filename></link> <link linkend='toaster-command-builddelete'><filename>builddelete</filename></link>
command. command.
For example, assuming default repository and build directory Here is an example that assumes default repository and build
names, the following two commands put you in the directory names:
<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
and then return a list of the current builds, which would
be one in this case:
<literallayout class='monospaced'> <literallayout class='monospaced'>
$ cd $HOME/poky/build $ cd ~/poky/build
$ python ../bitbake/lib/toaster/manage.py buildslist $ python ../bitbake/lib/toaster/manage.py buildslist
</literallayout>
If your Toaster database had only one build, the above
<filename>buildslist</filename> command would return something
like the following:
<literallayout class='monospaced'>
1: qemux86 poky core-image-minimal 1: qemux86 poky core-image-minimal
</literallayout> </literallayout>
</para> </para>
@@ -1000,7 +1004,7 @@
<literallayout class='monospaced'> <literallayout class='monospaced'>
$ bitbake/lib/toaster/manage.py checksettings $ bitbake/lib/toaster/manage.py checksettings
</literallayout> </literallayout>
In Managed Mode, Toaster uses settings that are based on the In Build Mode, Toaster uses settings that are based on the
database to configure the building tasks. database to configure the building tasks.
The <filename>checksettings</filename> command verifies that The <filename>checksettings</filename> command verifies that
the database settings are valid in the sense that they have the database settings are valid in the sense that they have
@@ -1026,8 +1030,8 @@
<title><filename>loadconf</filename></title> <title><filename>loadconf</filename></title>
<para> <para>
The <filename>loadconf</filename> command loads a Toaster The <filename>loadconf</filename> command loads an
configuration file (JSON file). existing Toaster configuration file (JSON file).
You must run this on a new database that does not have any You must run this on a new database that does not have any
data. data.
Running this command on an existing database that has data Running this command on an existing database that has data
@@ -1037,8 +1041,8 @@
$ bitbake/lib/toaster/manage.py loadconf <replaceable>filepath</replaceable> $ bitbake/lib/toaster/manage.py loadconf <replaceable>filepath</replaceable>
</literallayout> </literallayout>
The <filename>loadconf</filename> command configures a database The <filename>loadconf</filename> command configures a database
based on the supplied <filename>toasterconf.json</filename> based on the supplied existing
file. <filename>toasterconf.json</filename> file.
For information on the <filename>toasterconf.json</filename>, For information on the <filename>toasterconf.json</filename>,
see the see the
"<link linkend='toaster-json-files'>JSON Files</link>" "<link linkend='toaster-json-files'>JSON Files</link>"
@@ -1050,7 +1054,7 @@
<title><filename>runbuilds</filename></title> <title><filename>runbuilds</filename></title>
<para> <para>
The <filename>runbuilds</filename> command launched The <filename>runbuilds</filename> command launches
scheduled builds. scheduled builds.
Access the command as follows: Access the command as follows:
<literallayout class='monospaced'> <literallayout class='monospaced'>
@@ -1061,8 +1065,8 @@
per schedule. per schedule.
The command returns after the builds start but before they The command returns after the builds start but before they
complete. complete.
The "toasterui" build recorded updates the database when the The Toaster Logging Interface records and updates the database
builds complete. when the builds complete.
</para> </para>
</section> </section>
</section> </section>

117
documentation/toaster-manual/toaster-manual-setup-and-use.xml
View File

@@ -209,7 +209,7 @@
you install and set up a front-end web server. you install and set up a front-end web server.
This server allows for load balancing and This server allows for load balancing and
multi-threading over Toaster and multi-threading over Toaster and
<filename>django</filename> WSGI. <ulink url='https://docs.djangoproject.com/en/1.7/howto/deployment/wsgi/'><filename>django</filename> WSGI</ulink>.
Here is an example that uses Apache web server. Here is an example that uses Apache web server.
<literallayout class='monospaced'> <literallayout class='monospaced'>
$ apt-get install apache2 libapache2-mod-wsgi $ apt-get install apache2 libapache2-mod-wsgi
@@ -282,19 +282,41 @@
</para></listitem> </para></listitem>
<listitem><para><emphasis>Enable Build Logging to the Common SQL Server for Each Build Directory you are Using:</emphasis> <listitem><para><emphasis>Enable Build Logging to the Common SQL Server for Each Build Directory you are Using:</emphasis>
In the Build Directory, create the required In the Build Directory, create the required
<filename>conf/toaster.conf</filename> file as <filename>conf/toaster.conf</filename> file by doing
described in the following:
<ulink url='https://wiki.yoctoproject.org/wiki/Setting_up_a_local_instance_of_Toaster'>BitBake Extra Options</ulink>. <note>
Briefly, for each Build Directory, you need to inherit The following statements are automatically added
the to the <filename>toaster.conf</filename> file
<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-toaster'>toaster</ulink> when Toaster starts through the
class by setting the following in your <filename>toaster start</filename> command.
<filename>local.conf</filename> configuration file: </note>
<literallayout class='monospaced'> <itemizedlist>
<listitem><para>
Be sure that Toaster inherits the
<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-toaster'><filename>toaster</filename></ulink>
class and it is enabled in Bitbake in order to
record target image package information:
<literallayout class='monospaced'>
INHERIT += "toaster" INHERIT += "toaster"
</literallayout>
</para></listitem>
<listitem><para>
Enable build history in BitBake.
Build history is needed to record target image
package information:
<literallayout class='monospaced'>
INHERIT += "buildhistory" INHERIT += "buildhistory"
BUILDHISTORY_COMMIT = "1" BUILDHISTORY_COMMIT = "1"
</literallayout> </literallayout>
This last command is not strictly needed.
However, without it build history will not
properly work.
For information on build history, see the
"<ulink url='&YOCTO_DOCS_REF_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>"
section in the Yocto Project Development
Manual.
</para></listitem>
</itemizedlist>
You also need to point to the database. You also need to point to the database.
You can do this by exporting the You can do this by exporting the
<filename>DATABASE_URL</filename> variable as follows: <filename>DATABASE_URL</filename> variable as follows:
@@ -434,8 +456,7 @@
Toaster configuration file. Toaster configuration file.
Toaster configurations are stored in Toaster configurations are stored in
JSON files called JSON files called
<filename>toasterconf.json</filename> and supports <filename>toasterconf.json</filename>.
several types.
For information on JSON files, see the For information on JSON files, see the
"<link linkend='toaster-json-files'>JSON Files</link>" "<link linkend='toaster-json-files'>JSON Files</link>"
section.</para> section.</para>
@@ -498,27 +519,6 @@
MANAGED="True" MANAGED="True"
</literallayout> </literallayout>
</para></listitem> </para></listitem>
<listitem><para><emphasis>Configure the Build Environment:</emphasis>
Configure the build environment by running the
following:
<literallayout class='monospaced'>
bitbake/lib/toaster/manage.py checksettings
</literallayout>
For reference information on Toaster-specific
<filename>manage.py</filename> commands, see the
"<link linkend='toaster-useful-commands'>Useful Commands</link>"
section.
</para></listitem>
<listitem><para><emphasis>Load a Configuration File:</emphasis>
Load a configuration file by running the following:
<literallayout class='monospaced'>
bitbake/lib/toaster/manage.py loadconf <replaceable>path-to-toasterconf.json-file</replaceable>
</literallayout>
For reference information on Toaster-specific
<filename>manage.py</filename> commands, see the
"<link linkend='toaster-useful-commands'>Useful Commands</link>"
section.
</para></listitem>
<listitem><para><emphasis>Set Up Toaster for Normal Usage:</emphasis> <listitem><para><emphasis>Set Up Toaster for Normal Usage:</emphasis>
You need to configure each build environment, layer You need to configure each build environment, layer
sources, and BitBake versions.</para> sources, and BitBake versions.</para>
@@ -675,7 +675,7 @@
build artifacts, downloading sources, and running build artifacts, downloading sources, and running
builds. builds.
All three directories need to be writable by All three directories need to be writable by
the "poky" user. the user, which is "poky" in this example.
The build artifacts directory needs to readable by the The build artifacts directory needs to readable by the
apache user. apache user.
You also need free disk space in the range of You also need free disk space in the range of
@@ -688,33 +688,42 @@
</literallayout> </literallayout>
</para></listitem> </para></listitem>
<listitem><para><emphasis>Set Up the <filename>toasterconf.json</filename> File:</emphasis> <listitem><para><emphasis>Set Up the <filename>toasterconf.json</filename> File:</emphasis>
Download the <filename>toasterconf.json</filename> file <ulink url='https://wiki.yoctoproject.org/wiki/File:Toasterconf.json.txt.patch'>Download the hosted <filename>toasterconf.json</filename> file</ulink>
from the from the Yocto Project wiki and edit it to suit your
<ulink url='https://wiki.yoctoproject.org/wiki/File:Toasterconf.json.txt.patch'>File:Toasterconf.json.txt.patch</ulink> environment.
wiki page and edit it to suit your environment.
For information on the relevant sections of the file, For information on the relevant sections of the file,
see the see the
"<link linkend='toaster-json-files'>JSON Files</link>" "<link linkend='toaster-json-files'>JSON Files</link>"
section.</para>
<para>After editing the file, load it by running
the following:
<literallayout class='monospaced'>
$ bitbake/lib/toaster/manage.py loadconf path-to-toasterconf.json-file
</literallayout>
For reference information on Toaster-specific
<filename>manage.py</filename>, see the
"<link linkend='toaster-useful-commands'>Useful Commands</link>"
section. section.
</para></listitem> </para></listitem>
<listitem><para><emphasis>Check the Toaster Settings:</emphasis> <listitem><para><emphasis>Check the Toaster Settings:</emphasis>
You can check the Toaster settings by running this Configure the build environment by running the
command: following:
<literallayout class='monospaced'> <literallayout class='monospaced'>
$ bitbake/lib/toaster/manage.py checksettings $ bitbake/lib/toaster/manage.py checksettings
</literallayout> </literallayout>
When prompted, paste in the directory paths created When prompted, paste in the directory paths created
previously during Step 9. previously during Step 7.
Alternatively, you can select the edited For reference information on Toaster-specific
<filename>toasterconf.json</filename> file set up in <filename>manage.py</filename>, see the
Step 5. "<link linkend='toaster-useful-commands'>Useful Commands</link>"
section.
</para></listitem> </para></listitem>
<listitem><para><emphasis>Install and Set Up the Web Server:</emphasis> <listitem><para><emphasis>Install and Set Up the Web Server:</emphasis>
For a production environment, it is recommended that For a production environment, it is recommended that
you install and set up a front-end web server. you install and set up a front-end web server.
This server allows for load balancing and This server allows for load balancing and
multi-threading over Toaster and multi-threading over Toaster and
<filename>django</filename> WSGI. <ulink url='https://docs.djangoproject.com/en/1.7/howto/deployment/wsgi/'><filename>django</filename> WSGI</ulink>.
Here is an example that uses Apache web server: Here is an example that uses Apache web server:
<literallayout class='monospaced'> <literallayout class='monospaced'>
$ apt-get install apache2 libapache2-mod-wsgi $ apt-get install apache2 libapache2-mod-wsgi
@@ -764,7 +773,7 @@
</literallayout> </literallayout>
</para></listitem> </para></listitem>
<listitem><para><emphasis>Start Toaster:</emphasis> <listitem><para><emphasis>Start Toaster:</emphasis>
Synchronize the databases for toaster, and then start Synchronize the databases for Toaster, and then start
up the web server. up the web server.
Here is an example that continues with the assumed Here is an example that continues with the assumed
components from the previous steps: components from the previous steps:
@@ -803,13 +812,13 @@
<listitem><para><emphasis>Open the Browser:</emphasis> <listitem><para><emphasis>Open the Browser:</emphasis>
Once the Apache server is running, connect to it with Once the Apache server is running, connect to it with
your favorite browser and verify that the Toaster your favorite browser and verify that the Toaster
interface comes up. interface comes up:
You can track accesses and errors in the Apache
service logs:
<literallayout class='monospaced'> <literallayout class='monospaced'>
http://localhost:8000/toastergui http://localhost:8000/toastergui
</literallayout> </literallayout>
You can now use the Toaster web interface. You can now use the Toaster web interface to do thing
such as track accesses and errors in the Apache
service logs.
</para></listitem> </para></listitem>
</orderedlist> </orderedlist>
</para> </para>
@@ -823,8 +832,10 @@
The Toaster web interface allows you to do the following: The Toaster web interface allows you to do the following:
<itemizedlist> <itemizedlist>
<listitem><para> <listitem><para>
Browse all OpenEmbedded layers available for your Browse published layers in the
selected version of the build system <ulink url='http://layers.openembedded.org'>OpenEmbedded Metadata Index</ulink>
that are available for your selected version of the build
system.
</para></listitem> </para></listitem>
<listitem><para> <listitem><para>
Import your own layers for building. Import your own layers for building.

4
documentation/toaster-manual/toaster-manual.xml
View File

@@ -33,7 +33,7 @@
<revhistory> <revhistory>
<revision> <revision>
<revnumber>1.8</revnumber> <revnumber>1.8</revnumber>
<date>Sometime in 2015</date> <date>October 2015</date>
<revremark>Released with the Yocto Project 1.8 Release.</revremark> <revremark>Released with the Yocto Project 1.8 Release.</revremark>
</revision> </revision>
</revhistory> </revhistory>
@@ -51,7 +51,7 @@
<note> <note>
For the latest version of this manual associated with this For the latest version of this manual associated with this
Yocto Project release, see the Yocto Project release, see the
<ulink url='&YOCTO_DOCS_ADT_URL;'>Toaster User Manual</ulink> <ulink url='&YOCTO_DOCS_TOAST_URL;'>Toaster User Manual</ulink>
from the Yocto Project website. from the Yocto Project website.
</note> </note>