README for morph ================ > **NOTA BENE:** This document is very much work-in-progress, and anything > and everything may and will change at little or no notice. If you see > problems, mail baserock-dev@baserock.org. `morph` builds binaries for [Baserock](http://www.baserock.org/), an appliance Linux solution. Please see the website for overall information. Usage ----- The Baserock builds are controlled by Baserock definitions files. See the documentation at for information on the format. `morph --help` will provide some information, though a full guide is really required. Meanwhile a short usage to build a disk image: git clone git://git.baserock.org/baserock/baserock/definitions cd definitions morph build systems/base-system-x86_64-generic.morph For deploying you need to create a cluster morphology. Here is an example to deploy to a raw disk image. name: base-system-x86_64-rawdisk kind: cluster systems: - morph: systems/base-system-x86_64-generic.morph deploy: my-raw-disk-image: type: extensions/rawdisk location: base-system-x86_64.img DISK_SIZE: 4G To deploy it, you only need to run `morph deploy` with the cluster morphology created: morph deploy foo.morph You can write a configuration file to avoid having to write options on the command line every time. Put it in `~/.morph.conf` and make it look something like this: [config] cachedir = /home/username/baserock/cache log = /home/username/baserock/morph.log log-max = 200M trove-host = git.baserock.org All of the above settings apart from `log` are the defaults, so may be omitted. Running `morph` outside Baserock -------------------------------- It used to be the case that `morph` had to be run from within an existing Baserock system, however it is now possible to run `morph` from a general Linux host system; this has currently been demonstrated to work on Debian, Ubuntu and Fedora on x86_64, and Ubuntu on 64-bit little-endian ARMv8. Morph needs to be run as root user. As such, system configurations required to run `morph` independently, and which are tied to a particular user, must also be applied to root. * Install dependencies (on Debian-like systems) sudo apt-get install linux-user-chroot python-pip build-essential git m4 * Install dependencies (on Fedora systems) sudo dnf install linux-user-chroot python-pip git m4 sudo dnf install make automake gcc gcc-c++ kernel-devel * Install dependencies (all) sudo pip install --user fs pylru jsonschema pyyaml * Set-up sudo git config --global user.name 'Your Name' sudo git config --global user.email 'your.email@address.org' * Clone sources git clone git://git.baserock.org/baserock/baserock/definitions.git git clone git://git.baserock.org/baserock/baserock/morph.git cd definitions * Start a build sudo ../morph/morph build systems/base-system-x86_64-generic.morph You may optionally create a `/root/.morph.conf` configuration in the same way as above to configure `morph`, for example to add a log file. Build environment ----------------- When `morph` runs build commands, it clears the environment of all variables and creates new ones. This is so that the build will run more consistently across machines and developers. See the `morphlib/buildenvironment.py` file for details on what environment variables are set. Morph also constructs a staging area for every build, composed of its build-dependencies, so everything that is used for a build is traceable and reproducible. Hacking morph ------------- When running Morph from a Git checkout, remember to set PYTHONPATH to point to your checkout. This will cause Morph to load the plugins and write extensions from your checkout correctly. Run the test suite with this command: ./check If your /tmp is a tmpfs you may need to set TMPDIR to a different path, as there are tests for large disk image deploys. Install CoverageTestRunner (from ), and check out the `cmdtest` utility (from ). Run the checks before submitting a patch, please. Legalese -------- Copyright (C) 2011-2016 Codethink Limited This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; version 2 of the License. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see .