View source for BKM: Packaging a BSP for Release

== Packaging a BSP for Release ==

This explains, in a very general way, how to structure a BSP for release. As the structure of different board support packages can be slightly different, we suggest that you review the [[http://www.yoctoproject.org/docs/current/bsp-guide/bsp-guide.html | Yocto Project BSP Guide]]

=== General Guidelines ===

* A BSP should contain a root level binary directory to contain binary images. Enough to get a board to boot with some level of functionality, keeping in mind that the larger the image, the longer it takes for people to download your BSP
* A BSP should contain *just* the meta-data needed to at least rebuild the images that exist in /binary. If your BSP repo contains support for 10 BSPs, the BSP tarball you release SHOULD NOT contain all of that meta-data.
* A BSP tarball should contain a MAINTAINERS and a README file
* A BSP tarball should contain licensing information
* A BSP tarball does NOT need to contain the version of the poky/oe-core repo it was built with, however, it SHOULD be built with a known released version of poky and/or oe-core
* When requesting the release of a BSP, you should be able to provide the git hash the images were built against, for ALL layers. So, if you built images that contained meta-intel and poky, you should be able to provide both git hashes.
* In general the purpose of releasing a BSP is to make it easier for the end user to duplicate your work. Prior to requesting a release, please, test that someone can use your BSP and get the same results.

=== Example structure ===

For our example, we will utilize the meta-intel BSP, meta-fri2.


 <nowiki>
-rw-r--r--	MAINTAINERS
-rw-r--r--	README
d---------	classes
d---------	common
d---------	conf
d---------	meta-chiefriver
d---------	meta-crownbay
d---------	meta-crystalforest
d---------	meta-emenlow
d---------	meta-fri2
d---------	meta-isg
d---------	meta-jasperforest
d---------	meta-n450
d---------	meta-nuc
d---------	meta-romley
d---------	meta-sugarbay
d---------	meta-sys940x
d---------	meta-tlk
</nowiki>
The top level directory of the meta-intel repo contains multiple BSPs, and classes, common and conf directories. 

For our example, we will be using fri2. What we will first do is remove all BSPs that are not fri2:

 <nowiki>
-rw-r--r--	MAINTAINERS
-rw-r--r--	README
d---------	classes
d---------	common
d---------	conf
d---------	meta-fri2
d---------	meta-tlk
</nowiki>

You will notice that we have left the meta-tlk directory. As meta-intel images are built with a time limited kernel, we need to include this, both to ensure end users have the ability to recreate our work and also to maintain open source license compliance.

 <nowiki>
-rw-r--r--	MAINTAINERS
-rw-r--r--	README
d---------	binary
d---------	classes
d---------	common
d---------	conf
d---------	meta-fri2
d---------	meta-tlk
</nowiki>

Next, we will add a binary directory. This should contain the images needed to get hardware to boot.

We will then tar the image up in either tar.bz2 or tar.gz (tar.bz2 is much prefered). Please do not utilize non-standard compression formats.

The naming convention for the tarball is:

<name of bsp>-<name of release it was built against>-M.m.p

We do not generally care what the name of the file expands to, HOWEVER, please ensure that whatever it expands to is exactly the same as what it is documented as.

=== Addendum on why to include or not to include poky/oe-core ===

There are a few very good reasons why you would not want to include poky with your BSP, as well a some good ones as to why. Previously, organizations released with poky at the root directory and their BSP included in the directory.

We initially suggested including poky with the BSP releases for two major reasons. GPL compliance and ease of use for the end user. The general consensus now, is that this is generally something we want to avoid.

While a single checkout BSP may make things a bit easier for the end user, it can lead to the end user not being up to date with poky and thus releasing against an old poky release which may include unresolved CVEs. Also a BSP should always be able to build against the HEAD of the branch it was originally released against. For example, a BSP released and built against the yocto-1.5 "dora" release should always be able to build against future revisions of yocto-1.5. By releasing a BSP with a pegged version of poky, the end user can get confused as to this concept.