From 00fe95d133fdb6fcdd982afe7f27a77bb021f788 Mon Sep 17 00:00:00 2001 From: Belen Date: Mon, 14 Mar 2016 18:40:58 +0000 Subject: toaster-manual: Explain the local release The fact that the Local Yocto Project release does not provide any compatible layers confuses people. Add a section about the local release to explain what it does. [YOCTO #9229] (From yocto-docs rev: cc7ebcd5a66ff3041a7fdd17e697dfb60b08cadd) Signed-off-by: Belen Signed-off-by: Richard Purdie --- .../toaster-manual/figures/compatible-layers.png | Bin 0 -> 163081 bytes .../toaster-manual/figures/import-layer.png | Bin 0 -> 139108 bytes .../toaster-manual/figures/new-project.png | Bin 0 -> 73760 bytes .../toaster-manual-setup-and-use.xml | 954 +++++++++++---------- 4 files changed, 509 insertions(+), 445 deletions(-) create mode 100644 documentation/toaster-manual/figures/compatible-layers.png create mode 100644 documentation/toaster-manual/figures/import-layer.png create mode 100644 documentation/toaster-manual/figures/new-project.png (limited to 'documentation/toaster-manual') diff --git a/documentation/toaster-manual/figures/compatible-layers.png b/documentation/toaster-manual/figures/compatible-layers.png new file mode 100644 index 0000000000..38436b075c Binary files /dev/null and b/documentation/toaster-manual/figures/compatible-layers.png differ diff --git a/documentation/toaster-manual/figures/import-layer.png b/documentation/toaster-manual/figures/import-layer.png new file mode 100644 index 0000000000..436ec7af4a Binary files /dev/null and b/documentation/toaster-manual/figures/import-layer.png differ diff --git a/documentation/toaster-manual/figures/new-project.png b/documentation/toaster-manual/figures/new-project.png new file mode 100644 index 0000000000..dbc50b9918 Binary files /dev/null and b/documentation/toaster-manual/figures/new-project.png differ diff --git a/documentation/toaster-manual/toaster-manual-setup-and-use.xml b/documentation/toaster-manual/toaster-manual-setup-and-use.xml index 3e05eb2828..2e465f432b 100644 --- a/documentation/toaster-manual/toaster-manual-setup-and-use.xml +++ b/documentation/toaster-manual/toaster-manual-setup-and-use.xml @@ -115,451 +115,515 @@ To access the Django administration interface, you must create a superuser by following these steps: - - If you used virtualenv, which is - recommended, to set up the Toaster system dependencies, - you need be sure the virtual environment is activated. - To activate this environment, use the following: - - $ source venv/bin/activate - - - - From the directory containing the Toaster database, - which by default is the - Build Directory, - invoke the createsuperuser command - from manage.py: - - $ cd ~/poky/build - $ ../bitbake/lib/toaster/manage.py createsuperuser - - - - Django prompts you for the username, which you need to - provide. - - - Django prompts you for an email address, which is - optional. - - - Django prompts you for a password, which you must provide. - - - Django prompts you to re-enter your password for verification. - - - After completing these steps, the following confirmation message - appears: - - Superuser created successfully. - - - - - Creating a superuser allows you to access the Django administration - interface through a browser. - The URL for this interface is the same as the URL used for the - Toaster instance with "/admin" on the end. - For example, if you are running Toaster locally, use the - following URL: - - http://127.0.0.1:8000/admin - - You can use the Django administration interface to set Toaster - configuration parameters such as the build directory, layer sources, - default variable values, and BitBake versions. - - - -
- Setting Up a Production Instance of Toaster - - - You can use a production instance of Toaster to share the - Toaster instance with remote users, multiple users, or both. - The production instance is also the setup that can cope with - heavier loads on the web service. - Use the instructions in the following sections to set up - Toaster to run builds through the Toaster web interface. - - -
- Requirements - - - Be sure you meet the following requirements: - - You must comply with all Apache, - mod-wsgi, and Mysql requirements. - - - - Have all the build requirements as described in - "Setting Up the Basic System Requirements" - chapter. - - - Have an Apache webserver. - - - Have mod-wsgi for the Apache - webserver. - - - Use the Mysql database server. - - - If you are using Ubuntu 14.04.3, run the following: - - $ sudo apt-get install apache2 libapache2-mod-wsgi mysql-server virtualenv libmysqlclient-dev - - - - If you are using Fedora 22 or a RedHat distribution, run - the following: - - $ sudo dnf install httpd mod_wsgi python-virtualenv gcc mysql-devel - - - - -
- -
- Installation - - - Perform the following steps to install Toaster: - - - Checkout a copy of poky - into the web server directory. - You will be using /var/www/toaster: - - $ mkdir -p /var/www/toaster - $ cd /var/www/toaster/ - $ git clone git://git.yoctoproject.org/poky - $ git checkout &DISTRO_NAME; - - - - Initialize a virtual environment and install Toaster - dependencies. - Using a virtual environment keeps the Python packages - isolated from your system-provided packages: - - $ cd /var/www/toaster/ - $ virtualenv venv - $ source ./venv/bin/activate - $ pip install -r ./poky/bitbake/toaster-requirements.txt - $ pip install mysql - $ pip install MySQL-python - - - Isolating these packages is not required but is - recommended. - Alternatively, you can use your operating system's - package manager to install the packages. - - - - Configure Toaster by editing - /var/www/toaster/poky/bitbake/lib/toaster/toastermain/settings.py - as follows: - - - Edit the DATABASE settings: - - DATABASES = { - 'default': { - 'ENGINE': 'django.db.backends.mysql', - 'NAME': 'toaster_data', - 'USER': 'toaster', - 'PASSWORD': 'yourpasswordhere', - 'HOST': 'localhost', - 'PORT': '3306', - } - } - - - - Edit the SECRET_KEY: - - SECRET_KEY = 'your_secret_key' - - - - Edit the STATIC_ROOT: - - STATIC_ROOT = '/var/www/toaster/static_files/' - - - - - - Add the database and user to the mysql - server defined earlier: - - $ mysql -u root -p - mysql> CREATE DATABASE toaster_data; - mysql> CREATE USER 'toaster'@'localhost' identified by 'yourpasswordhere'; - mysql> GRANT all on toaster_data.* to 'toaster'@'localhost'; - mysql> quit - - - - Get Toaster to create the database schema, - default data, and gather the statically-served files: - - $ cd /var/www/toaster/poky/ - $ ./bitbake/lib/toaster/manage.py syncdb - $ ./bitbake/lib/toaster/manage.py migrate - $ TOASTER_DIR=`pwd` TOASTER_CONF=./meta-yocto/conf/toasterconf.json ./bitbake/lib/toaster/manage.py checksettings - $ ./bitbake/lib/toaster/manage.py collectstatic - - - - - For the above set of commands, after moving to the - poky directory, - the syncdb and migrate - commands ensure the database - schema has had changes propagated correctly (i.e. - migrations). - - - - The next line sets the Toaster root directory - TOASTER_DIR and the location of - the Toaster configuration file - TOASTER_CONF, which is - relative to the Toaster root directory - TOASTER_DIR. - For more information on the Toaster configuration file - TOASTER_CONF, see the - JSON Files - section of this manual. - - - - This line also runs the checksettings - command, which configures the location of the Toaster - Build directory. - The Toaster root directory TOASTER_DIR - determines where the Toaster build directory - is created on the file system. - In the example above, - TOASTER_DIR is set as follows: - - /var/www/toaster/poky - - This setting causes the Toaster build directory to be: - - /var/www/toaster/poky/build - - - - - Finally, the collectstatic command - is a Django framework command that collects all the - statically served files into a designated directory to - be served up by the Apache web server. - - - Add an Apache configuration file for Toaster to your Apache web - server's configuration directory. - If you are using Ubuntu or Debian, put the file here: - - /etc/apache2/conf-available/toaster.conf - - If you are using Fedora or RedHat, put it here: - - /etc/httpd/conf.d/toaster.conf - - Following is a sample Apache configuration for Toaster - you can follow: - - Alias /static /var/www/toaster/static_files - <Directory /var/www/toaster/static_files> - Order allow,deny - Allow from all - Require all granted - </Directory> - - WSGIDaemonProcess toaster_wsgi python-path=/var/www/toaster/poky/bitbake/lib/toaster:/var/www/toaster/venv/lib/python2.7/site-packages - - WSGIScriptAlias / "/var/www/toaster/poky/bitbake/lib/toaster/toastermain/wsgi.py" - <Location /> - WSGIProcessGroup toastern_wsgi - </Location> - - If you are using Ubuntu or Debian, - you will need to enable the config and module for Apache: - - $ sudo a2enmod wsgi - $ sudo a2enconf toaster - $ chmod +x bitbake/lib/toaster/toastermain/wsgi.py - - Finally, restart Apache to make sure all new configuration - is loaded. - For Ubuntu and Debian use: - - $ sudo service apache2 restart - - For Fedora and RedHat use: - - $ sudo service httpd restart - - - - Install the build runner service. - This service needs to be running in order to dispatch - builds. - Use this command: - - /var/www/toaster/poky/bitbake/lib/toaster/manage.py runbuilds - - Here is an example: - - #!/bin/sh - # toaster run builds dispatcher - cd /var/www/toaster/ - source ./venv/bin/activate - ./bitbake/lib/toaster/manage.py runbuilds - - - - You can now open up a browser and start using Toaster. - -
-
- -
- Using the Toaster Web Interface - - - The Toaster web interface allows you to do the following: - - - Browse published layers in the - OpenEmbedded Metadata Index - that are available for your selected version of the build - system. - - - Import your own layers for building. - - - Add and remove layers from your configuration. - - - Set configuration variables. - - - Select a target or multiple targets to build. - - - Start your builds. - - - See what was built (recipes and packages) and what - packages were installed into your final image. - - - Browse the directory structure of your image. - - - See the value of all variables in your build configuration, - and which files set each value. - - - Examine error, warning and trace messages to aid in - debugging. - - - See information about the BitBake tasks executed and - reused during your build, including those that used - shared state. - - - See dependency relationships between recipes, packages - and tasks. - - - See performance information such as build time, task time, - CPU usage, and disk I/O. - - - - -
- Toaster Web Interface Videos - - - Following are several videos that show how to use the Toaster GUI: - - Build Configuration: - This - video - overviews and demonstrates build configuration for Toaster. - - Build Custom Layers: - This - video - shows you how to build custom layers that are used with - Toaster. - - Toaster Homepage and Table Controls: - This - video - goes over the Toaster entry page, and provides - an overview of the data manipulation capabilities of - Toaster, which include search, sorting and filtering by - different criteria. - - Build Dashboard: - This - video - shows you the build dashboard, a page providing an - overview of the information available for a selected build. - - Image Information: - This - video - walks through the information Toaster provides - about images: packages installed and root file system. - - Configuration: - This - video - provides Toaster build configuration information. - - Tasks: - This - video - shows the information Toaster provides about the - tasks run by the build system. - - Recipes and Packages Built: - This - video - shows the information Toaster provides about recipes - and packages built. - - Performance Data: - This - video - shows the build performance data provided by - Toaster. - - - -
- -
- Building a Specific Recipe Given Multiple Versions + + If you used virtualenv, which is + recommended, to set up the Toaster system dependencies, + you need be sure the virtual environment is activated. + To activate this environment, use the following: + + $ source venv/bin/activate + + + + From the directory containing the Toaster database, + which by default is the + Build Directory, + invoke the createsuperuser command + from manage.py: + + $ cd ~/poky/build + $ ../bitbake/lib/toaster/manage.py createsuperuser + + + + Django prompts you for the username, which you need to + provide. + + + Django prompts you for an email address, which is + optional. + + + Django prompts you for a password, which you must provide. + + + Django prompts you to re-enter your password for verification. + + + After completing these steps, the following confirmation message + appears: + + Superuser created successfully. + + + + + Creating a superuser allows you to access the Django administration + interface through a browser. + The URL for this interface is the same as the URL used for the + Toaster instance with "/admin" on the end. + For example, if you are running Toaster locally, use the + following URL: + + http://127.0.0.1:8000/admin + + You can use the Django administration interface to set Toaster + configuration parameters such as the build directory, layer sources, + default variable values, and BitBake versions. + +
+ +
+ Setting Up a Production Instance of Toaster + + + You can use a production instance of Toaster to share the + Toaster instance with remote users, multiple users, or both. + The production instance is also the setup that can cope with + heavier loads on the web service. + Use the instructions in the following sections to set up + Toaster to run builds through the Toaster web interface. + + +
+ Requirements + + + Be sure you meet the following requirements: + + You must comply with all Apache, + mod-wsgi, and Mysql requirements. + + + + Have all the build requirements as described in + "Setting Up the Basic System Requirements" + chapter. + + + Have an Apache webserver. + + + Have mod-wsgi for the Apache + webserver. + + + Use the Mysql database server. + + + If you are using Ubuntu 14.04.3, run the following: + + $ sudo apt-get install apache2 libapache2-mod-wsgi mysql-server virtualenv libmysqlclient-dev + + + + If you are using Fedora 22 or a RedHat distribution, run + the following: + + $ sudo dnf install httpd mod_wsgi python-virtualenv gcc mysql-devel + + + + +
+ +
+ Installation + + + Perform the following steps to install Toaster: + + + Checkout a copy of poky + into the web server directory. + You will be using /var/www/toaster: + + $ mkdir -p /var/www/toaster + $ cd /var/www/toaster/ + $ git clone git://git.yoctoproject.org/poky + $ git checkout &DISTRO_NAME; + + + + Initialize a virtual environment and install Toaster + dependencies. + Using a virtual environment keeps the Python packages + isolated from your system-provided packages: + + $ cd /var/www/toaster/ + $ virtualenv venv + $ source ./venv/bin/activate + $ pip install -r ./poky/bitbake/toaster-requirements.txt + $ pip install mysql + $ pip install MySQL-python + + + Isolating these packages is not required but is + recommended. + Alternatively, you can use your operating system's + package manager to install the packages. + + + + Configure Toaster by editing + /var/www/toaster/poky/bitbake/lib/toaster/toastermain/settings.py + as follows: + + + Edit the DATABASE settings: + + DATABASES = { + 'default': { + 'ENGINE': 'django.db.backends.mysql', + 'NAME': 'toaster_data', + 'USER': 'toaster', + 'PASSWORD': 'yourpasswordhere', + 'HOST': 'localhost', + 'PORT': '3306', + } + } + + + + Edit the SECRET_KEY: + + SECRET_KEY = 'your_secret_key' + + + + Edit the STATIC_ROOT: + + STATIC_ROOT = '/var/www/toaster/static_files/' + + + + + + Add the database and user to the mysql + server defined earlier: + + $ mysql -u root -p + mysql> CREATE DATABASE toaster_data; + mysql> CREATE USER 'toaster'@'localhost' identified by 'yourpasswordhere'; + mysql> GRANT all on toaster_data.* to 'toaster'@'localhost'; + mysql> quit + + + + Get Toaster to create the database schema, + default data, and gather the statically-served files: + + $ cd /var/www/toaster/poky/ + $ ./bitbake/lib/toaster/manage.py syncdb + $ ./bitbake/lib/toaster/manage.py migrate + $ TOASTER_DIR=`pwd` TOASTER_CONF=./meta-yocto/conf/toasterconf.json ./bitbake/lib/toaster/manage.py checksettings + $ ./bitbake/lib/toaster/manage.py collectstatic + + + + + For the above set of commands, after moving to the + poky directory, + the syncdb and migrate + commands ensure the database + schema has had changes propagated correctly (i.e. + migrations). + + + + The next line sets the Toaster root directory + TOASTER_DIR and the location of + the Toaster configuration file + TOASTER_CONF, which is + relative to the Toaster root directory + TOASTER_DIR. + For more information on the Toaster configuration file + TOASTER_CONF, see the + JSON Files + section of this manual. + + + + This line also runs the checksettings + command, which configures the location of the Toaster + Build directory. + The Toaster root directory TOASTER_DIR + determines where the Toaster build directory + is created on the file system. + In the example above, + TOASTER_DIR is set as follows: + + /var/www/toaster/poky + + This setting causes the Toaster build directory to be: + + /var/www/toaster/poky/build + + + + + Finally, the collectstatic command + is a Django framework command that collects all the + statically served files into a designated directory to + be served up by the Apache web server. + + + Add an Apache configuration file for Toaster to your Apache web + server's configuration directory. + If you are using Ubuntu or Debian, put the file here: + + /etc/apache2/conf-available/toaster.conf + + If you are using Fedora or RedHat, put it here: + + /etc/httpd/conf.d/toaster.conf + + Following is a sample Apache configuration for Toaster + you can follow: + + Alias /static /var/www/toaster/static_files + <Directory /var/www/toaster/static_files> + Order allow,deny + Allow from all + Require all granted + </Directory> + + WSGIDaemonProcess toaster_wsgi python-path=/var/www/toaster/poky/bitbake/lib/toaster:/var/www/toaster/venv/lib/python2.7/site-packages + + WSGIScriptAlias / "/var/www/toaster/poky/bitbake/lib/toaster/toastermain/wsgi.py" + <Location /> + WSGIProcessGroup toastern_wsgi + </Location> + + If you are using Ubuntu or Debian, + you will need to enable the config and module for Apache: + + $ sudo a2enmod wsgi + $ sudo a2enconf toaster + $ chmod +x bitbake/lib/toaster/toastermain/wsgi.py + + Finally, restart Apache to make sure all new configuration + is loaded. + For Ubuntu and Debian use: + + $ sudo service apache2 restart + + For Fedora and RedHat use: + + $ sudo service httpd restart + + + + Install the build runner service. + This service needs to be running in order to dispatch + builds. + Use this command: + + /var/www/toaster/poky/bitbake/lib/toaster/manage.py runbuilds + + Here is an example: + + #!/bin/sh + # toaster run builds dispatcher + cd /var/www/toaster/ + source ./venv/bin/activate + ./bitbake/lib/toaster/manage.py runbuilds + + + + You can now open up a browser and start using Toaster. + +
+
+ +
+ Using the Toaster Web Interface + + + The Toaster web interface allows you to do the following: + + + Browse published layers in the + OpenEmbedded Metadata Index + that are available for your selected version of the build + system. + + + Import your own layers for building. + + + Add and remove layers from your configuration. + + + Set configuration variables. + + + Select a target or multiple targets to build. + + + Start your builds. + + + See what was built (recipes and packages) and what + packages were installed into your final image. + + + Browse the directory structure of your image. + + + See the value of all variables in your build configuration, + and which files set each value. + + + Examine error, warning and trace messages to aid in + debugging. + + + See information about the BitBake tasks executed and + reused during your build, including those that used + shared state. + + + See dependency relationships between recipes, packages + and tasks. + + + See performance information such as build time, task time, + CPU usage, and disk I/O. + + + + +
+ Toaster Web Interface Videos + + + Following are several videos that show how to use the Toaster GUI: + + Build Configuration: + This + video + overviews and demonstrates build configuration for Toaster. + + Build Custom Layers: + This + video + shows you how to build custom layers that are used with + Toaster. + + Toaster Homepage and Table Controls: + This + video + goes over the Toaster entry page, and provides + an overview of the data manipulation capabilities of + Toaster, which include search, sorting and filtering by + different criteria. + + Build Dashboard: + This + video + shows you the build dashboard, a page providing an + overview of the information available for a selected build. + + Image Information: + This + video + walks through the information Toaster provides + about images: packages installed and root file system. + + Configuration: + This + video + provides Toaster build configuration information. + + Tasks: + This + video + shows the information Toaster provides about the + tasks run by the build system. + + Recipes and Packages Built: + This + video + shows the information Toaster provides about recipes + and packages built. + + Performance Data: + This + video + shows the build performance data provided by + Toaster. + + + +
+ +
+ A Note on the Local Yocto Project Release + + + This note only applies if you have set up Toaster + for local development, as explained in + + section 3.1. + + + When you create a project in Toaster, you will be asked to + provide a name and to select a Yocto Project release. One + of the release options you will find is called + Local Yocto Project. + + + + + When you select the Local Yocto Project + release, Toaster will run your builds using the local Yocto + Project clone you have in your computer: the same clone + you are using to run Toaster. Unless you manually update + this clone, your builds will always use the same Git revision. + + + + If you select any of the other release options, Toaster + will fetch the tip of your selected release from the upstream + Yocto Project + repository every time you run a build. This effectively + means that if your selected release is updated upstream, the + Git revision you are using for your builds will change. + If you are doing development locally, you might not want this + to happen. In that case, the Local Yocto Project + release might be the right choice. + + + + However, the Local Yocto Project release + will not provide you with any compatible layers, other than the + three core layers that come with the Yocto Project: + + + openembedded-core + + + meta-poky + + + meta-yocto-bsp + + + + + + + If you want to build any other layers, you will need to + manually import them into your Toaster project, using the + Import layer page. + + + +
+ +
+ Building a Specific Recipe Given Multiple Versions Occasionally, a layer might provide more than one version of -- cgit v1.2.3-54-g00ecf