Build Process

= Introduction =

This document describes the build process for BCCD. The legacy process describes the old <code>build_livecd.pl</code> script; the improved process will describe the replacement for it.

= Legacy process =

The legacy process is driven by the <code>bin/build_livecd.pl</code> script in SVN. This script turns 8 years old on April 14, 2015 and, while functional, represents a much more rudimentary time for BCCD, both in terms of the distribution support and the team's (mainly Skylar's) software development knowledge.

The purpose of this section will be to document this legacy process comprehensively, and take inventory of its deficiencies so as to create the [[#Improved process|improved process]].

== Relationship with <code>Bccd.pm</code> ==

<code>build_livecd.pl</code> makes heavy use of <code>Bccd.pm</code>. <code>Bccd.pm</code> itself has a number of deficiencies itself:

* Poor error-handling - it will either log or die, when current best-practice for Perl is to throw an exception by returning <code>undef</code>, and catch in <code>eval</code>
* Excessively large methods
* Poor logging - logging should be built-in rather than requiring use of <code>if</code>/<code>else</code>
* Global filehandles - these should be scoped scalars
* Too many methods - should be broken up into multiple classes w/ inheritance

== Legacy process details ==

The legacy process has the following stages:

<ul>
 <li>Configuration:</li>
 <ol>
  <li>Parse the YAML configuration file in the workspace into a hash reference</li>
  <li>Override configuration keys via command line option</li>
 </ol>
 <li>Debmirror - set the local debian mirror host so that we don't overload Earlham's Internet connection</li>
 <li>Hard coded settings - a large block of hard-coded settings
</ul>

== Legacy process deficiencies ==

* Tests are integrated with the build, making test-driven development difficult/impossible
* Error reporting is inconsistent
* Object orientation implementation gets in the way, some things might be better implemented as a simple library, with OO where appropriate
** Object orientation might be useful for some things, e.g. handling networking configuration for multiple NICs
* Some architecture-specific actions are hard-coded into the build
** Would be nice to support other architectures like ARM

= Improved process =

See also: the [[Talk:Build Process|talk page]]

== Build stages ==

The improved process is a Make-/[[Jenkins]]-driven pipeline. The <code>Makefile</code> lives in the root of the SVN branch/tag. The Jenkins pipeline consists of the following stages:

=== <code>debootstrap</code> ===

; Artifact : <code>target/debootstrap.tar.bz2</code>
; Make target : <code>target/debootstrap.tar.bz2</code>
; Triggers : [[Build_Process#debootstrap-bccd|<code>debootstrap-bccd</code>]]

Produces the artifact by running the <code>bin/prepare_debootstrap</code> script.

=== <code>fpm</code> ===

; Artifact : <code>target/bccd.noarch.deb</code>, <code>build/etc/bccd-revision</code>
; Make target : <code>target/bccd.noarch.deb</code>
; Triggers : [[Build_Process#debootstrap-bccd|<code>debootstrap-bccd</code>]]

Generates <code>bccd.noarch.deb</code> using <code>rpm</code> and the checked-out files in the <code>src</code> directory.

=== <code>debootstrap-bccd</code> ===

; Dependencies : <code>target/debootstrap.tar.bz2</code>, <code>build/etc/bccd-revision</code>
; Artifact : <code>target/debootstrap-bccd.tar.bz2</code>
; Make target : <code>target/debootstrap-bccd.tar.bz2</code>
; Triggers : [[Build_Process#iso|<code>iso</code>]]

Unpacks <code>target/debootstrap.tar.bz2</code>, runs <code>bin/bccd_install_pkgs</code> within it, and then creates <code>target/debootstrap-bccd.tar.bz2</code>

'''NOTE''': Both the [[Build_Process#debootstrap|<code>debootstrap</code>]] and [[Build_Process#fpm|<code>fpm</code>]] will trigger this target. <code>debootstrap</code> only has to be run when updating the OS, while <code>fpm</code> needs to be run when the BCCD package is updated.

=== <code>iso</code> ===

; Dependencies : <code>target/bccd.noarch.deb</code>, <code>build/etc/bccd-revision</code>, <code>target/debootstrap-bccd.tar.bz2</code>
; Make target : <code>target/bccd.amd64.iso</code>

Unpacks <code>debootstra-bccd.tar.bz2</code>, installs <code>target/bccd.noarch.deb</code> within, then produces a <code>filesystem.squashfs</code> artifact, and finally an ISO image containing the <code>squashfs</code>.