[Toaster] Changes to the Toaster manual

[Michael Wood]

Hi Scott,

Comments in-line

On 21/10/15 16:46, Scott Rifenbark wrote:
> Hi,
>
> See my in-line comments for all these issues.  There are two 
> outstanding issues surrounding blocks of commands (see below).  I need 
> some further explanation for context.
>
> http://www.yoctoproject.org/docs/2.0/toaster-manual/toaster-manual.html
>
> Thanks
>
> On Wed, Oct 21, 2015 at 2:44 AM, Barros Pena, Belen 
> <belen.barros.pena at intel.com <mailto:belen.barros.pena at intel.com>> wrote:
>
>
>
>     On 20/10/2015 20:06, "Scott Rifenbark" <srifenbark at gmail.com
>     <mailto:srifenbark at gmail.com>> wrote:
>
>     >Hi,
>     >
>     >
>     >I got the chapter 3 changes roughed in. Can't get to the small
>     chapter 2
>     >change until later.  Here is the link to review the chapter 3 stuff -
>     >
>     >http://www.yoctoproject.org/docs/2.0/toaster-manual/toaster-manual.html#to
>     >aster-manual-setup-and-use
>     ><http://www.yoctoproject.org/docs/2.0/toaster-manual/toaster-manual.html#t
>     >oaster-manual-setup-and-use>.
>
>     Thanks for this, Scott. Just a few omments:
>
>     * "(e.g. "Build Mode")," > this is not an example, it is one of the
>     operational modes explained in 1.1. Toaster Operational Modes. We
>     don't
>     have an anchor to the build mode within that 1.1. Section, but if
>     we could
>     split it and create one, that 'build mode' string should be a link
>     to the
>     explanation of the build mode in the operational modes section.
>
>
> Correct.. I should have used "i.e.", which means "that is".  I created 
> the anchor to "build mode" and set up the link.
>
>
>     * "to the root of your Toaster source directory:" > I don't think it
>     should say the 'Toaster source directory'. People didn't clone
>     Toaster:
>     they cloned / downloaded the 2.0 Yocto Project release. That's the
>     source
>     directory they need to navigate to. Maybe we should just use
>     "navigate to
>     the root of your source directory", which you use further down.
>
>
> Ok - I have used the established "Source Directory" term that is 
> consistently used to point to "poky", which is used in this example.  
> I linked to the definition, which is in the dev-manual and added the 
> "for example" notational e.g. to link to that definition.
>
>
>     * "If you would rather configure and start your builds using the
>     command
>     line" > maybe we should add here "analysis mode" and link it to the
>     corresponding explanation in the toaster operational modes section
>
>
> I changed this to be parallel to how we did the "Build Mode" item above.
>
>
>     * Section 3.3 > I think I am missing something. I don't understand
>     what
>     "execute path_to_poky/bitbake/bin/toaster" is supposed to mean. Maybe
>     Brian can explain (he wrote that bit). Also, I think the path is
>     wrong.
>     The _toaster_clones directory is created inside poky
>     (poky/_toaster_clones) not inside
>     poky/bitbake/bin/toaster/_toaster_clones. It also says "if you
>     used the
>     following command to start Toaster", but then no command is shown.
>     Are we
>     missing the path_to_poky/bitbake/bin/toaster command here?
>
>
> OK - after some clarification from Belen I have re-written this to be 
> correct.
>
>
>     * Section 3.4 > all the above also applies to this section. The build
>     directory is inside poky (poky/build) not
>     poky/bitbake/bin/toaster/build.
>     We are also missing the command you need to execute:
>     path_to_poky/bitbake/bin/toaster
>
>
> Got it.. updated to match the previous section.
>
>
>     * 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. > we need to test
>     this. It
>     used to be the case, but I am not sure what's happening now after
>     the set
>     up changes made by Brian
>
>
> I see from further down in this email thread that you have tested this 
> so I am leaving it as is.
>
>
>     * to set up Toaster in Build Mode > this should again link to the
>     explanation of the build mode in the operational modes section
>
>
> Done.
>
>
>     * Section 3.6.1 > the commands shown for Ubuntu and Fedora make
>     sure you
>     comply with the apache, mod-wsgi and mysql requirements state
>     above, but
>     that is not explicit from the layout.
>
>
> Not sure how you want this addressed.  So, I have added a note. Check 
> it out and let me know if this is okay.
>
>
>     * # change for any release name required > Only jethro and fido will
>     support this kind of set up, I think, so maybe we should remove that
>     sentence
>
>
> I replaced "jethro" in the command to use the variable &DISTRO_NAME, 
> which resolves to the "jethro" in this case.  It should never resolve 
> to anything prior to "jethro".  I took out the commented part of the 
> command.
>
>
>     * Make sure you make this edit further down in the file from where
>     BUILD_MODE is set based on the TOASTER_MANAGED environment
>     variable > I am
>     not sure I understand this sentence. Does it mean that I have to add
>     BUILD_MODE after TOASTER_MANAGED in the file?
>
>
> I added a note about this requirement and attempted to make it more clear.


TOASTER_MANAGED is an internal implementation detail now and does not 
need to be mentioned.

In section 3.6.2 step 3 the only instruction needed is "Set BUILD_MODE" 
to True.


>
>
>     * Get Toaster to create the database schema, default data, and
>     gather the
>     statically-served files: > should we break down the steps here to
>     explain
>     what each line does? Those are not obvious for people outside
>     toaster-land.
>
>
> I sent Belen a chat on Jabber regarding this comment.  I don't know 
> how these commands break out.  So if someone can provide some details 
> on these four commands I can wrap some context around them:
>
> $ ./bitbake/lib/toaster/manage.py syncdb --migrate

This is a django-south command See 
https://south.readthedocs.org/en/latest/commands.html


> $ ./bitbake/lib/toaster/manage.py loadconf 
> ./meta-yocto/conf/toasterconf.json

http://www.yoctoproject.org/docs/2.0/toaster-manual/toaster-manual.html#toaster-command-loadconf

> $ ./bitbake/lib/toaster/manage.py lsupdates

This fetches the initial recipes and layers data from the layer index.


> $ ./bitbake/lib/toaster/manage.py collectstatic

This is a django framework command for collecting up all the statically 
served files into a designated directory to be served up by the 
webserver (Apache in the case of this documentation)

https://docs.djangoproject.com/en/1.7/ref/contrib/staticfiles/

>
>     * Here are the commands: > I am not sure what those commands are
>     for. Can
>     we explain?
>
>
> So for this area of the manual, I basically cut and pasted the stuff 
> from the file given to me.  I am clueless on what these commands do.  
> Can someone provide some explanation around this block of commands?
>
> 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>
>


This part isn't a command, it's a sample Apache configuration for 
Toaster, it needs to be written and placed in the directory mentioned in 
the instructions.


Thanks,

Michael

>
>     >
>     >
>     >Note that I left the section in on using the web interface.  I am
>     >assuming that stuff stays.
>
>     Yes, although I'd like to list one more video if possible, about
>     building
>     custom layers with Toaster. The video is here:
>
>     https://www.youtube.com/watch?v=QJzaE_XjX5c
>
>
> Added to the list of current vids.
>
>
>
>
>     Thanks!
>
>     Belén
>
>     >
>     >
>     >Let me know of any changes by using this email thread.
>     >
>     >
>     >Thanks,
>     >
>     >Scott
>     >
>     >
>     >On Mon, Oct 19, 2015 at 4:09 AM, Barros Pena, Belen
>     ><belen.barros.pena at intel.com
>     <mailto:belen.barros.pena at intel.com>> wrote:
>     >
>     >I have gone through the list of changes we put together for the
>     Toaster
>     >manual, and most of them are already there. There is only one thing
>     >pending: changing Chapter 3, the one about setting up and using
>     Toaster.
>     >
>     >The team has put together some new content for that section as a
>     starting
>     >point. It's here
>     >
>     >http://piratepad.nl/YzSI38RuYd
>     >
>     >Note that it includes also some changes for section 2.1 (at the
>     very top).
>     >
>     >There are 2 gaps in this new content:
>     >
>     >1. How to change the default location of the layers checkout
>     directory
>     >2. How to change the default location of the build directory
>     >
>     >Brian: do you think you could add the above missing information
>     to the
>     >pad, so that Scott can make the changes to the manual (if he has
>     time)?
>     >
>     >Thanks!
>     >
>     >Belén
>     >
>     >
>     >
>     >
>     >
>     >
>
>