Merge pull request #314 from YoeDistro/cbrake/master

documentation updates

docs/conf-files.md

@@ -4,21 +4,24 @@
 
 OpenEmbedded is configured through "conf" files. These exist at various
 [places](https://www.yoctoproject.org/docs/latest/mega-manual/mega-manual.html#user-configuration)
-in the sources. At the top level of the project are several files that
-contain high level, or build specific configuration options. For the Yoe
-project, these files include:
+in the sources. At the top level of the project are several files that contain
+high level, or build specific configuration options. For the Yoe project, these
+files include:
 
-- **conf/auto.conf**: This file is automatically generated by the the build system
-  and should not be modified.
+- **conf/auto.conf**: This file is automatically generated by the the build
+  system and should not be modified.
 - [**conf/site.conf**](../conf/site.conf): This file includes Yoe defaults and
-  project specific changes that you want to store in git.
-  This [file](../conf/site.conf.sample) includes samples of things you might want to add.
-- **conf/local.conf**: This file includes changes that are specific to a user or build
-  machine, and are not checked into git. This [file](../conf/local.conf.sample) includes
-  samples of things you might want to add.
+  project specific changes that you want to store in git. This
+  [file](../conf/site.conf.sample) includes samples of things you might want to
+  add.
+- **conf/local.conf**: This file includes changes that are specific to a user or
+  build machine, and are not checked into git. This
+  [file](../conf/local.conf.sample) includes samples of things you might want to
+  add.
 
 The above configuration files are included into the build by the
-[bitbake.conf](https://github.com/YoeDistro/openembedded-core/blob/master/meta/conf/bitbake.conf#L744) file in the OpenEmbedded Core layer.
+[bitbake.conf](https://github.com/YoeDistro/openembedded-core/blob/master/meta/conf/bitbake.conf#L744)
+file in the OpenEmbedded Core layer.
 
 For a full list of variables available in the OpenEmbedded build system, see the
 [Variables Glossary](https://www.yoctoproject.org/docs/latest/mega-manual/mega-manual.html#ref-variables-glos).

docs/docker.md

@@ -2,25 +2,28 @@
 
 [up](README.md)
 
-The Yoe project provides a [docker container](https://hub.docker.com/r/yoedistro/yoe-build/)
-that has all the dependencies needed to build Yoe. This container is mostly transparent
-as it simply wraps the bitbake command. Every time you run bitbake, the container is started
-and all bitbake operations happen in the container. The build files still exist in the host
-file system so they can be accessed using any of your host tools.
+The Yoe project provides a
+[docker container](https://hub.docker.com/r/yoedistro/yoe-build/) that has all
+the dependencies needed to build Yoe. This container is mostly transparent as it
+simply wraps the bitbake command. Every time you run bitbake, the container is
+started and all bitbake operations happen in the container. The build files
+still exist in the host file system so they can be accessed using any of your
+host tools.
 
-Using this container has the following
-benefits:
+Using this container has the following benefits:
 
 - you don't have to worry about installing host dependencies
-- you can build on any Linux host distro, even those that are not compatible with Yoe
-- as host distributions are updated, then eventually become incompatible with older
-  versions of OpenEmbedded. Using a container allows you to build old version of Yoe
-  over long product life cycles.
+- you can build on any Linux host distro, even those that are not compatible
+  with Yoe
+- as host distributions are updated, then eventually become incompatible with
+  older versions of OpenEmbedded. Using a container allows you to build old
+  version of Yoe over long product life cycles.
 
-Yoe uses docker by default, but this can be disabled by setting `DOCKER_REPO=none` in your
-_\<project\>-envsetup.sh_ file. You can also set `DOCKER_REPO` to a custom container if
-you need something different.
+Yoe uses docker by default, but this can be disabled by setting
+`DOCKER_REPO=none` in your _\<project\>-envsetup.sh_ file. You can also set
+`DOCKER_REPO` to a custom container if you need something different.
 
-Any tool (such as `devtool`) that uses bitbake must also be run in the container. As these
-tools are not yet wrapped, you must enter the docker container first, and then run the tool.
-This can be done by running `dkr` first, which drops you into a container shell.
+Any tool (such as `devtool`) that uses bitbake must also be run in the
+container. As these tools are not yet wrapped, you must enter the docker
+container first, and then run the tool. This can be done by running `dkr` first,
+which drops you into a container shell.

docs/gcc.md

@@ -2,17 +2,20 @@
 
 [up](README.md)
 
-The primary use for OE is to cross-compile software on a fast workstation, but there are
-times during development or evaluating technology where it may be useful to compile
-software on the target device. There is also some software that is simply too nasty for
-most of us to figure out how to cross-compile so one workaround is to build a binary on
-the target system, and then package that binary in subsequent image builds.
-This _hack_ should only be used as a _last resort_ in production builds.
+The primary use for OE is to cross-compile software on a fast workstation, but
+there are times during development or evaluating technology where it may be
+useful to compile software on the target device. There is also some software
+that is simply too nasty for most of us to figure out how to cross-compile so
+one workaround is to build a binary on the target system, and then package that
+binary in subsequent image builds. This _hack_ should only be used as a _last
+resort_ in production builds.
 
-The following packages can be added to the image, or installed at runtime using a package
-manager such as opkg.
+The following packages can be added to the image, or installed at runtime using
+a package manager such as opkg.
 
-- `packagegroup-core-buildessential` - this is most often what you need and is very similiar
-  to the build-essential package on Debian/Ubuntu. [recipe](https://github.com/YoeDistro/openembedded-core/blob/master/meta/recipes-core/packagegroups/packagegroup-core-buildessential.bb)
-- `packagegroup-self-hosted` - a much more extensive list of packages that includes what is
-  in buildessential, plus a lot more. [recipe](https://github.com/YoeDistro/openembedded-core/blob/master/meta/recipes-core/packagegroups/packagegroup-self-hosted.bb)
+- `packagegroup-core-buildessential` - this is most often what you need and is
+  very similiar to the build-essential package on Debian/Ubuntu.
+  [recipe](https://github.com/YoeDistro/openembedded-core/blob/master/meta/recipes-core/packagegroups/packagegroup-core-buildessential.bb)
+- `packagegroup-self-hosted` - a much more extensive list of packages that
+  includes what is in buildessential, plus a lot more.
+  [recipe](https://github.com/YoeDistro/openembedded-core/blob/master/meta/recipes-core/packagegroups/packagegroup-self-hosted.bb)

docs/git-submodules.md

@@ -2,19 +2,25 @@
 
 [up](README.md)
 
-Git submodules are used in this project to manage the various OE layers for reasons
-described in [this document](superproject-management.md). There are a few issues
-that are commonly encountered.
+Git submodules are used in this project to manage the various OE layers for
+reasons described in [this document](superproject-management.md). See this
+[article](https://www.atlassian.com/git/tutorials/git-submodule) for an
+introduction to Git submodules.
+
+There are a few issues that are commonly encountered decsribed below.
 
 ## Modifying Submodules
 
-Git submodules are not checked out as branch, but simply a git version. The first
-thing you should do when working on a submodule is check out the appropriate branch,
-documented in the [.gitmodules](../.gitmodules) file. If you forget to do this, you
-may get an error when pushing and then if you run `git branch`, you'll discover you
-are on the _(no branch)_ branch. To recover from this situation, check out the
-branch you want to work on and then run `git reflog`. This command will list recent
-commits which you can then cherry-pick to your working branch.
+Git submodules are not checked out as branch, but simply a git version. The
+first thing you should do when working on a submodule is check out the
+appropriate branch, documented in the [.gitmodules](../.gitmodules) file. If you
+forget to do this, you may get an error when pushing and then if you run
+`git branch`, you'll discover you are on the _(no branch)_ branch. To recover
+from this situation, check out the branch you want to work on and then run
+`git reflog`. This command will list recent commits which you can then
+cherry-pick to your working branch. See this
+[article](http://bec-systems.com/site/696/git-submodules-what-to-do-when-you-commit-to-no-branch)
+for more information.
 
 ## Submodule merge conflicts
 
@@ -24,4 +30,5 @@ If you get a submodule merge conflict, run `git reset \<sources/submodule\>`
 
 If the remote repository for a submodule changes, run `git submodule sync` to
 synchronize the new remote information into your working directory. This problem
-is most often noticed when the `git submodule update` command cannot find a version.
+is most often noticed when the `git submodule update` command cannot find a
+version.

docs/layer-management.md

@@ -2,16 +2,33 @@
 
 [up](README.md)
 
-All OE layers that are being used in Yoe project are mirrored in the YoeDistro space on github. These layers are synced every two hours with upstream since the global namespace is kept intact, there are no conflicts. We reserve namespaces for local branches
+All OE layers that are being used in Yoe project are mirrored in the YoeDistro
+space on github. These layers are synced every two hours with upstream since the
+global namespace is kept intact, there are no conflicts. We reserve namespaces
+for local branches
 
-* ```yoe/<topic>``` - Distro Specific branch, needed when we have to do distro speicific fixes which are not upstreamable, this is rare situation, secondly, we create additional layers e.g. yoe/mut ( mut stands for "Master-Under-Test) branches which are used for regular CI builds. 
+- `yoe/<topic>` - Distro Specific branch, needed when we have to do distro
+  speicific fixes which are not upstreamable, this is rare situation, secondly,
+  we create additional layers e.g. yoe/mut ( mut stands for "Master-Under-Test)
+  branches which are used for regular CI builds.
+
+- `<user>/<topic>` - This namespace is reserved for developers, these are also
+  short lived branches primarily used for development which are deleted after
+  pull request is accepted in a public branch
 
-* ```<user>/<topic>``` - This namespace is reserved for developers, these are also short lived branches primarily used for development which are deleted after pull request is accepted in a public branch
-
 ## Why do we mirror the layers ?
 
-* This provides needed redundancy and development space for Yoe Distro developers. Since we create pure mirrors for public branches and offer namespaces for development, this makes it a good combination for hosting changes when they are in flight. It also provides a mechanism for running a CI loop on the changes to be submitted upstream for specific layers.
+- This provides needed redundancy and development space for Yoe Distro
+  developers. Since we create pure mirrors for public branches and offer
+  namespaces for development, this makes it a good combination for hosting
+  changes when they are in flight. It also provides a mechanism for running a CI
+  loop on the changes to be submitted upstream for specific layers.
+
+- If a product is to be released one can easily mirror the yoe mirrors
+  internally and keep a local copy, or one can use same mirroring policy and
+  local branching policy to create internal branches. Just keep <yoe>/ namespace
+  safe.
 
-* If a product is to be released one can easily mirror the yoe mirrors internally and keep a local copy, or one can use same mirroring policy and local branching policy to create internal branches. Just keep <yoe>/ namespace safe.
-
-* For some reason if upstream layers disappear and we still need to maintain the layers, which can happen over a long life of products, then we offer a redundancy
+- For some reason if upstream layers disappear and we still need to maintain the
+  layers, which can happen over a long life of products, then we offer a
+  redundancy

docs/packages.md

@@ -2,26 +2,30 @@
 
 [up](README.md)
 
-During an image build, OpenEmbedded builds all software into packages, which are then
-combined into a rootfs. One benefit of this is you can install packages later into a
-running system, much like you would a desktop distribution like Debian, Ubuntu, Arch,
-etc. OE supports the RPM, DEB, and IPK package formats, and the format can be set using the
+During an image build, OpenEmbedded builds all software into packages, which are
+then combined into a rootfs. One benefit of this is you can install packages
+later into a running system, much like you would a desktop distribution like
+Debian, Ubuntu, Arch, etc. OE supports the RPM, DEB, and IPK package formats,
+and the format can be set using the
 [PACKAGE_CLASSES](https://www.yoctoproject.org/docs/latest/mega-manual/mega-manual.html#var-PACKAGE_CLASSES)
 variable.
 
 ## Installing packages from a local build
 
-You can install packages directly from your local OE build onto a target system with the
-following procedure:
+You can install packages directly from your local OE build onto a target system
+with the following procedure:
 
 - packaging information must be included in the target image:
   - `IMAGE_FEATURES += "packages-management"`
 - a ssh server must be enabled in the target image:
   - `IMAGE_FEATURES += "ssh-server-dropbear"`
-- see [yoe-simple-image](https://github.com/YoeDistro/meta-yoe/blob/master/recipes-core/images/yoe-simple-image.bb) for an example.
+- see
+  [yoe-simple-image](https://github.com/YoeDistro/meta-yoe/blob/master/recipes-core/images/yoe-simple-image.bb)
+  for an example.
 - target system must be on the same network as your build computer.
-- run `yoe_setup_feed_server <target ip address>`. This configures the target to fetch packages
-  from your build computer. Alternatively you can set the MACHINE_IP environment variable.
+- run `yoe_setup_feed_server <target ip address>`. This configures the target to
+  fetch packages from your build computer. Alternatively you can set the
+  MACHINE_IP environment variable.
 - run `yoe_feed_server`. This starts a web server that serves packages.
 - on target system, run:
   - `opkg update`
@@ -36,13 +40,13 @@ If the package is not built yet, simply:
   - `opkg update`
   - `opkg install <package>`
 
-This technique is very useful for testing new packages, or for installing packages that
-are only needed for development that you don't want to include in production images
-(strace, gdb, testing tools, etc). Dependencies are automatically handled by the package
-manager.
+This technique is very useful for testing new packages, or for installing
+packages that are only needed for development that you don't want to include in
+production images (strace, gdb, testing tools, etc). Dependencies are
+automatically handled by the package manager.
 
-For larger development teams or field deployments, you might want to set up a feed server
-to serve packages to any connected device.
+For larger development teams or field deployments, you might want to set up a
+feed server to serve packages to any connected device.
 
 See also:
 

docs/raspberrypi.md

@@ -18,8 +18,8 @@
 1. `sudo eject /dev/sdX`
 1. Install SD card in a Raspberry PI and enjoy your new image
 
-Other Raspberry Pi variants can be built by sourcing the appropriate
-envsetup file.
+Other Raspberry Pi variants can be built by sourcing the appropriate envsetup
+file.
 
 ## Enable serial console
 
@@ -30,9 +30,10 @@ in the BSP layer
 
 ## Connecting to rPI serial console
 
-The Raspberry PI serial console is avaiable on the expansion header. A USB->serial
-cable with flying leads is a convenient way to connect to this. [FTDI](https://www.ftdichip.com/Products/Cables/RPi.htm) (as well as many
-other companies supply these cables). The below image shows how the FTDI cable is
+The Raspberry PI serial console is avaiable on the expansion header. A
+USB->serial cable with flying leads is a convenient way to connect to this.
+[FTDI](https://www.ftdichip.com/Products/Cables/RPi.htm) (as well as many other
+companies supply these cables). The below image shows how the FTDI cable is
 connected:
 
 ![rPI serial console](raspberry-pi-serial-console.jpg)
@@ -43,10 +44,13 @@ The relevant signals are:
 - FTDI Yellow (RXD) <- rPI Pin8 (TXD)
 - FTDI Orange (TXD) -> rPI Pin10 (RXD)
 
-See the [schematics](https://www.raspberrypi.org/documentation/hardware/raspberrypi/schematics/README.md) for more information.
+See the
+[schematics](https://www.raspberrypi.org/documentation/hardware/raspberrypi/schematics/README.md)
+for more information.
 
 ## rPI Power Supply
 
-Some of the Raspberry PI products seem to be sensitive to power quality. It is recommended
-to use a supply that outputs 5.1V such as the [official supply](https://www.raspberrypi.org/products/raspberry-pi-universal-power-supply/). An inadequate supply may result in lockups or
-SD card file system corruption.
+Some of the Raspberry PI products seem to be sensitive to power quality. It is
+recommended to use a supply that outputs 5.1V such as the
+[official supply](https://www.raspberrypi.org/products/raspberry-pi-universal-power-supply/).
+An inadequate supply may result in lockups or SD card file system corruption.