Working in OpenXT

TODO this page needs updating.

The following assumes that you already have a built tree rooted in openxt.git with a completed build. It also assumes the build was done with with INHIBIT_RMWORK set. INHIBIT_RMWORK is set by default, and tells the build scripts to not delete the temporary packages build folders, so that we can go there, modify and rebuild source code.

The MACHINE variable

bitbake, the tool we use to build packages, uses the MACHINE environment variable to know what the current target (VM) is. A few possible values are xenclient-dom0 (to work on the main rootfs), xenclient-uivm (to work on the UI VM rootfs), xenclient-ndvm (to work on the network VM rootfs).

Make sure it is always set to something valid. Having "export MACHINE=xenclient-dom0" in your .bashrc is not a bad idea. If you are modifying multiple machines you can set it on the comment line before invoking the bb (which is a wrapper for the bitbake command).

The main folders

Folder	Description
`openxt.git/build/`	The main work folder, where bb (bitbake wrapper) lives
`openxt.git/build/repos`	Where all the OpenEmbedded repos get checked out
`openxt.git/build/repos/xenclient-oe/xenclient/recipes/`	The OpenXT-specific recipes (xenclient-oe.git)
`openxt.git/build/tmp-eglibc/`	The build folder, made not so "tmp" by INHIBIT_RMWORK
`openxt.git/build/tmp-eglibc/work/`	Where the building of the packages happen, each subfolder is an OE "machine"
`openxt.git/build/tmp-eglibc/work/core2-oe-linux/`	For non-machine-specific work, most of the non-kernel-related packages are built here

The package folders

Those are located in openxt.git/build/oe/tmp-eglibc/work/*/[Package name]_[Package version]/ and can contain the following folders:

Folder	Description
[Package name]-[Package version]/	The source code location for most non-git-based packages
git/	The source code location for git-based packages
image/	The build target folder, used to create the final packages
temp/	The build logs
deploy_ipks/*/	Where the final packages are

Custom bibake rules

To run in openxt.git/build using ./bb -c [rule] [Package name]

Rule	Description
makeclean	Run a proper "make clean" inside the build folder. IMPORTANT: rebuilding without cleaning could not do what you expect, like with Xen recipes. `makeclean` also does a `force_rebuild`
force_rebuild	Brings the state of the package back (usually from "done building") to "needs compiling"
cleansstate	Cleans the package and removes its state (which means "initial state" to OE)

Example

Let's say trousers build failed because of a typo in the code, here's how to fix it (some of the steps here can usually be skipped, like the rebuild at the beginning):

$ cd openxt.git/build
$ ./bb -c cleansstate trousers && ./bb trousers  # rebuild the package to make sure it's clean
$ less tmp-eglibc/work/core2-oe-linux/trousers-0.3.2-1-r2/temp/log.do_compile  # figure out what failed
$ vi tmp-eglibc/work/core2-oe-linux/trousers-0.3.2-1-r2/trousers-0.3.2-1/src/tcs/tcs_caps.c  # fix it
$ ./bb -c makeclean trousers # which does a -c force_rebuild
$ ./bb trousers
$ dpkg -c tmp-eglibc/work/core2-oe-linux/trousers-0.3.2-1-r2/deploy-ipks/core2/trousers_0.3.2-1-r2_core2.ipk  # check the contents of the final package

The case of dom0 Linux

Rebuilding Linux and updating a target is a bit more complicated and can break the target if not done properly.
Here's what to do after modifying the dom0 Linux code:

$ ./bb -c force_rebuild linux-xenclient-dom0 && ./bb linux-xenclient-dom0
$ ./bb -c cleansstate v4v-module && ./bb v4v-module  # This out-of-tree module needs to be updated as well
$ ./bb -c cleansstate xenclient-initramfs-image && ./bb xenclient-initramfs-image  # The initramfs needs the new modules
$ scp -r tmp-eglibc/work/xenclient_dom0-oe-linux/linux-xenclient-dom0*/deploy-ipks root@<target>:<folder>  # Send the new kernel
$ scp -r tmp-eglibc/work/xenclient_dom0-oe-linux/v4v-module*/deploy-ipks root@<target>:<folder>  # Send the new V4V module
$ scp tmp-eglibc/deploy/images/xenclient-initramfs-image-xenclient-dom0.cpio.gz root@<target>:<folder>  # Send the new initramfs
$ ssh root@<target>  # Connect to the target to put stuff where they belong
# nr  # Become sysadm
# rw  # Put the rootfs in rw
# lvresize -L+1G /dev/mapper/xenclient-root && resize2fs /dev/mapper/xenclient-root  # Frees some space, the default is usually not enough
# mv xenclient-initramfs-image-xenclient-dom0.cpio.gz /boot/initramfs.gz
# opkg install <every scp-ed ipk>
# # maybe fix some SELinux labels, or make SELinux permissive...
# ro
# reboot

This will obviously break any TPM measurement.

If, for example, you forgot the V4V module, the toolstack won't boot and the UI won't come up. In that case, simply reboot, choose the command line boot in grub, log in, enable networking (udhcpc -i eth0), and fix it.