########################
# HOWTO : Building Angstrom 
# using yocto/bitbake
########################

yocto: project for building custom embedded linux distros using openembedded bitbake
oebb: open embedded/bitbake
layer: bitbake layer, i.e. collection of recipes that adds or extends recipes
recipe: bitbake build recipe (.bb); data describing how to obtain and build the source for a package or image

########################
# references
########################
git://github.com/Angstrom-distribution/setup-scripts.git
http://www.yoctoproject.org/
https://www.yoctoproject.org/downloads/bsps/daisy16/beaglebone
http://www.yoctoproject.org/docs/current/ref-manual/ref-manual.html

http://elinux.org/Dummies_Guide_to_Building_Angstrom_Linux_for_MinnnowBoard
http://derekmolloy.ie/building-angstrom-for-beaglebone-from-source/
http://git.yoctoproject.org/cgit/cgit.cgi/meta-ti
https://github.com/Angstrom-distribution/meta-ti
http://hipstercircuits.com/compile-a-new-kernel-for-beaglebone/

http://www.crashcourse.ca/wiki/index.php/OE_variable_glossary
http://www.crashcourse.ca/wiki/index.php/BeagleBone#Building_Angstrom_for_BeagleBone

http://elene.dahners.com/blog/2012/10/22/compiling-a-kernel-module-for-beaglebone/
http://www.openembedded.org/wiki/Styleguide

########################
# Before starting
########################
- Ubuntu 12.04 LTS VM 
- other distros supported (Debian, Fedora, CentOS...)
- 60 GB disk recommended
- use bash as default shell

########################
# install packages
########################

# use sudo apt-get install 

# Essential
gawk install gawk wget git-core diffstat unzip 
texinfo gcc-multilib   build-essential chrpath

# Doc
make xsltproc docbook-utils fop dblatex xmlto

# ADT [probably good to have anyway]
autoconf automake libtool libglib2.0-dev

########################
# install yocto
########################

# get angstrom distro install scripts
# DO NOT install a distro-packaged version of bitbake. The metadata included in 
# various yocto layers only works with a particular version of bitbake. Angstrom and 
# Yocto will ensure the correct version is included when you check out the code.

git clone git://github.com/Angstrom-distribution/setup-scripts.git
cd setup-scripts
# show the available branches
git branch -a
 master
* remotes/origin/angstrom-v2014.06-yocto1.6
  remotes/origin/HEAD -> origin/master
  remotes/origin/angstrom-v2012.05-yocto1.2
  remotes/origin/angstrom-v2012.12-yocto1.3
  remotes/origin/angstrom-v2013.06-yocto1.4
  remotes/origin/angstrom-v2013.12-yocto1.5
  remotes/origin/angstrom-v2014.06-yocto1.6
  remotes/origin/master
  remotes/origin/next

# choose a stable branch
git checkout -b remotes/origin/angstrom-v2013.06-yocto1.4

# [optional] Add this to setup-scripts/conf/local.conf :
---- snip ----
# LICENSE_FLAGS_WHITELIST = "license_emgd-driver-bin commercial" : 
# This is  required to prevent the resulting image from including anything
# that might violate the license terms of the packages used to implement 
# the video acceleration feature,  such as gst-ffmpeg and ffmpeg.
LICENSE_FLAGS_WHITELIST = "license_emgd-driver-bin commercial" 

# NOISO = "1" : Due to a bug in ISO generation when building for EFI-only machines, 
# it is necessary to include this line in  your local.conf:
NOISO = "1"
---- snip ----

# configure yocto for beaglebone 
MACHINE=beaglebone ./oebb.sh config beaglebone

# update [shouldn't have much to do]
MACHINE=beaglebone ./oebb.sh update 

# source environment
# [should do this each build session, and not preface bitbake commands with 
# MACHINE=beaglebone ./oebb.sh ]
. environment-angstrom-v2013.12

# Build things 
# [intial/clean build takes hours]
bitbake virtual/kernel

# other things to build
# - other images (e.g. cloud9-image, systemd-image)
# - individual packages
# rebuild (clean) package or image
bitbake -c clean -f <package or image>

########################
# add xfoce layer
########################

########################
# add xfoce image (to meta-ti)
########################

########################
# build
########################
bitbake xfoce-bbone-images

########################
# deploy to SD Card
########################
plug in sd card reader
umount partitions (not device)
- sudo umount /dev/sdd1
- sudo umount /dev/sdd2
- sudo umount /dev/sdd3

sudo src/scripts/gwcard.yocto \
 -o /dev/sdd \
-x $XF_HOME \
-d $XF_HOME/xfoce-0.60.tar.gz \
-i /home/user/yocto/setup-scripts/deploy/eglibc/images/beaglebone

########################
# debugging tips
########################

- logs for each stage of  a package/image build (fetch, configure, compile, build, install)
are in build/tmp-<yada>/work/<target>/<package-version>/temp

- use the logs to see output from configure, make, etc. when things aren't working

########################
# missing symlink (libcrypto)
########################
After removing some of the beaglebone/nodejs/cloud9 components, xfoce build broke due to missing packages.
Resolution:
add these packages to the xfoce-bbone-image.bb recipe:
libcrypto , util-linux-dev, libmodbus , libmodbus-dev

The xfoce build is looking for
./lib/libcrypto.so -> libcrypto.so.1.0.0

# this works, but may not be the correct way:
# add ROOTFS_POSTPROCESS_COMMAND
# of IMAGE_POSTPROCESS_COMMAND
# line (which are nominally for .bbclass not .bb) to
# xfoce_bbone_image.bb recipe

ROOTFS_POSTPROCESS_COMMAND += "ln -s libcrypto.so.1.0.0 ${IMAGE_ROOTFS}/lib/librypto.so;"

########################
# license files
########################
- A license file is required in the recipe for packages, and an md5sum.
- The license file is usally called COPYING and is in the package root directory
- Typically, the file is part of the build, specified in the recipe as a FILE://<path>
where <path> is relative to the top of the package root. 
- oebb will provide the md5 sum in an error message if the sum is missing/incorrect (easy way), or you can compute it yourself if you have the package source (md5sum <path to license file>)

########################
# md5sum, sha256sum
########################
- oebb requires md5 and sha256 sums for downloaded packages
- if they are wrong in your recipe, the 
- oebb will provide the md5/sha256 sum in an error message if the sum is missing/incorrect

########################
# Problem w/ wget ssh certificates
########################
- 3.8.13 kernel, wget 8.13 
- wget had trouble w/ certificates on some github sites 
- e.g. http://github.com/downloads/stephane/libmodbus-3.0.3.tar.gz
- fails w/ ssl HELLO_HANDSHAKE error
- installed github ssl certificates on host, didn't work
Workaround:
- download source to sources/downloads
- use file:// fetcher in recipe

########################
# had trouble building socat 
# package: redifined symbols, 
# undefined symbols etc.
########################

- try building the package on the host using autotools (configure/make/make install) works)
- compared oebb configure logs 
- noted that CFLAGS were much simpler
- problem was that oebb runs autoreconf, and messes up dependencies.
- overrode oebb configure

do_configure(){
        ./configure  --build=i386-linux-gnu --host=gnu-linux-eabi --prefix=$(prefix)
}

- used default make and install

# some annotated recipes
# NOTES
# - socat no longer used; build digi realport drivers instead
# - libmodbus already included in angstrom core
# - lcm optional
# - xfoce optional (prefer to install latest)

########################
# zeromq_3.2.2.bb (1/3)
########################

SUMMARY = "ZeroMQ messaging library"
DESCRIPTION = "The 0MQ lightweight messaging kernel is \ 
a library which extends the standard socket interfaces \
with features traditionally provided by specialised \
messaging middleware products."
HOMEPAGE = "http://www.zeromq.org/"
SECTION = "libs/network"

LICENSE = "LGPLv3+"
LIC_FILES_CHKSUM = "file://COPYING.LESSER;md5=ad8c3bd15d88ea9d4509fc89bebc915c"

SRC_URI = "http://download.zeromq.org/${BP}.tar.gz"
#"https://github.com/zeromq/zeromq3-x.git"

inherit autotools pkgconfig

SRC_URI[md5sum] = ""
SRC_URI[sha256sum] = ""
#SRC_URI[md5sum] = "b5042d833c6c132e6fb2551af133a342"
#SRC_URI[sha256sum] = "6fc7cf91f7293e522afde6ae5fc605c6cd7bdca4ee2ec953db5bb91158ab8677"
require zeromq.inc

########################
# zeromq_git.bb (2/3)
########################

SRCREV = "v3.2.0"

PV = "3.2.0+gitr${SRCPV}"

PR = "${INC_PR}.0"

DEFAULT_PREFERENCE = "-1"

SRC_URI = "https://github.com/zeromq/zeromq3-x.git;branch=master;protocol=git"
S = "${WORKDIR}/git"

########################
# zeromq.inc (3/3)
########################
DESCRIPTION = "The 0MQ lightweight messaging kernel is \ 
a library which extends the standard socket interfaces \
with features traditionally provided by specialised \
messaging middleware products."
HOMEPAGE = "http://www.zeromq.org/"
SECTION = "libs/network"
LICENSE = "LGPLv3+"

SECTION = "libs/network"
PRIORITY = "optional"
INC_PR = "r0"

inherit autotools pkgconfig

########################
# xfoce_0.1.bb 
# [prefer to install latest distro]
########################
DESCRIPTION = "xFOCE firmware package"
HOMEPAGE = "http://www.xfoce.org"
LICENSE = "GPLv3"
SECTION = "console/scientific"
PRIORITY = "optional"
PR = "r0"

SRC_URI = "file:///home/headley/oe/sources/xfoce-0.1.tar.gz"

inherit autotools 

LIC_FILES_CHKSUM = "file://COPYING;md5=2a4b374377ac2f3f7867a789acae7e55"
SRC_URI[md5sum] = "bf57c9fce27fc96edfb2fa93163a0696"
SRC_URI[sha256sum] = "6e6c0fd9d2eefbd5cbd58e71bf3311d2a53d3ffe65f690bb46c0bd8602ffa1c5"

XFOCE_LDFLAGS = "'-L${STAGING_LIBDIR}/i386-linux-gnu'"
XFOCE_LIBS = "'-lpthread -lrt -lzmq'"

EXTRA_OECONF += "LDFLAGS=${XFOCE_LDFLAGS} LIBS=${XFOCE_LIBS}"

########################
# lcm
# [optional]
########################
DESCRIPTION = "Lightweight Communications and Marshalling"
HOMEPAGE = "https://code.google.com/p/lcm/"
LICENSE = "LGPLv3"

LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/LGPL-3.0;md5=bfccfe952269fff2b407dd11f2f3083b"

inherit autotools gettext pkgconfig
PR = "r0"

SRC_URI = "https://lcm.googlecode.com/files/lcm-${PV}.tar.gz"
SRC_URI[md5sum] = "3146793b15b5196eb48a10bc5f185bf5"
SRC_URI[sha256sum] = "23e3773b36bb73ff7ccc9b4076effe7530c96c00b8ecb171bfc2839b59517b0e"

S = "${WORKDIR}/lcm-${PV}"

#FILES_${PN}-dev += "lcm/usr/lib/*.so"
#FILES_${PN} += "/usr/bin/lcm-gen \
#/usr/bin/lcm-logplayer \
#/usr/bin/lcm-logger \
#/usr/include/* \
#/usr/lib/* \
#/usr/share/*"

########################
# libmodbus_3.0.3.bb (1/3)
########################
SUMMARY = "A Modbus library"
DESCRIPTION = "libmodbus is a C library designed to provide a fast and robust \
implementation of the Modbus protocol. It runs on Linux, Mac OS X, FreeBSD, \
QNX and Windows."
HOMEPAGE = "http://www.libmodbus.org/"
SECTION = "libs"

LICENSE = "LGPLv2.1+"
LIC_FILES_CHKSUM = "file://COPYING.LESSER;md5=4fbd65380cdd255951079008b364516c"

SRC_URI = "http://github.com/downloads/stephane/${BPN}/${BP}.tar.gz"

inherit autotools pkgconfig

SRC_URI[md5sum] = "b5042d833c6c132e6fb2551af133a342"
SRC_URI[sha256sum] = "6fc7cf91f7293e522afde6ae5fc605c6cd7bdca4ee2ec953db5bb91158ab8677"

########################
# libmodbus_git.bb (2/3)
########################
require libmodbus.inc

#SRCREV = "6254ede9156095ee0300"
SRCREV = "v3.0.3"

PV = "3.0.3+gitr${SRCPV}"

PR = "${INC_PR}.0"

DEFAULT_PREFERENCE = "-1"

SRC_URI = "git://github.com/stephane/libmodbus;branch=master;protocol=git"
S = "${WORKDIR}/git"

########################
# libmodbus.inc (3/3)
########################
DESCRIPTION = "A Modbus library for Linux, Mac OS X, FreeBSD, QNX and Win32"
HOMEPAGE = "http://www.libmodbus.org/"
SECTION = "libs"
PRIORITY = "optional"
LICENSE = "LGPLv2.1+"
INC_PR = "r0"

inherit autotools pkgconfig