UserBuildConfig & BuildProfiles

Work in Progress ...

In addition to configure options, UserBuildConfig is another, very powerful opportunity for customizing your build. As of changeset [29161], Haiku's build system supports two locations for UserBuildConfig:

$(HAIKU_TOP)/build/jam/UserBuildConfig
$(HAIKU_TOP) refers to the top level of your local copy of the svn tree. If you use an external object directory, the UserBuildConfig at this location will apply to all of them.
$(HAIKU_OUTPUT_DIR)/UserBuildConfig
Typically, $(HAIKU_OUTPUT_DIR) is $(HAIKU_TOP)/generated. However if you use an external object directory, then it UserBuildConfig is in that top-level directory. The UserBuildConfig in this file applies only to that object directory and over-rides $(HAIKU_TOP)/build/jam/UserBuildConfig.

Old Method vs Build Profiles

The only reason people continue using the old method, is because the new method isn't documented in the "guides" that are so rampant. Below is an example of the old method, followed by the new method that uses build profiles

Essentially, the 'old method' has UserBuildConfig listing all of the statements globally. This can cause unexpected results when used at the same time of build profiles. Ideally, UserBuildConfig files are created using build profiles and contain statements inside a case statement; this will ensure that the statements of one build profile do not affect another.

Old Method

HAIKU_IMAGE_DIR = /dev ;
HAIKU_IMAGE_NAME = sda2 ;
HAIKU_DONT_CLEAR_IMAGE = 1 ;

New Method -- Build Profile

DefineBuildProfile partition2 : disk : "/dev/sda2" ;
DefineBuildProfile my-custom-image : image : "customized-haiku.image" ;
switch $(HAIKU_BUILD_PROFILE) {
	case "partition2" : {
		Echo Building to partition2 ;
		# additional statements
	}
	case "my-*" : {
		Echo Building to custom image file ;
		HAIKU_IMAGE_SIZE = 2000 ;
		# additional statements
	}
}

(note the name you give it is up to you) and then use the following:

sudo chmod o+r /dev/sda
sudo chmod o+rw /dev/sda2
jam -q @partition2

Build Profiles

A very powerful feature of UserBuildConfig is the ability to create custom build profiles. Build profiles allow a user to create different configurations within the same UserBuildConfig. A particular configuration can then be targeted by running jam -q @. This can allow a user to set a limitless number of configurations; from a minimal target for creating emergency USB boot sticks, installing directly to partition, a VMWware image with more free space, and so on.

DefineBuildProfile rule

rule DefineBuildProfile name : type : path {
	# DefineBuildProfile  :  [ :  ]
	#
	# Makes a build profile known. Build profiles can be used to define
	# different sets of settings for Haiku images/installations. For each
	# profile the default actions "build", "update", and "mount" (the latter
	# only for disks or image types) will be available (i.e. can be specified
	# as second parameter on the jam command line). They will build an image
	# or installation, update only given targets, respectively just mount the
	# image or disk using the bfs_shell.
	#
	#  - The name of the build profile.
	#  - The type of the build profile. Must be one of "image" (plain
	#          disk image), "vmware-image" (VMware disk image), "disk"
	#          (actual partition or hard disk device), "cd-image" (ISO CD
	#          image), "install" (installation in a directory), or "custom"
	#          (user-defined).
	#  - The path associated with the profile. Depending on the profile
	#          type, this is the path to the disk image/VMware image, hard
	#          disk/partition device, or the installation directory. If the
	#          parameter is omitted, the value of the HAIKU[_VMWARE]_IMAGE_NAME,
	#          HAIKU_IMAGE_DIR, respectively HAIKU_INSTALL_DIR or their default
	#          values will be used instead.

Sample UserBuildConfig

The following sample UserBuildConfig is a working example, that displays some of the more complex usage. A simpler UserBuildConfig can be just as effective. For more information see UserBuildConfig.ReadMe , which is contained in the svn repository.

# Generate a string that describes the target platform
# eg,  x86gcc2hybrid,  x86gcc4, arm, ...,
# This string becomes part of the .image, .vmdk, or .iso filename.
#
local partialName = ;
if $(TARGET_ARCH) = x86 {
	if $(HAIKU_GCC_VERSION[1]) >= 4 {
		partialName = $(TARGET_ARCH)gcc4 ;
	} else {
		partialName = $(TARGET_ARCH)gcc2 ;
	}
	if $(HAIKU_ADD_ALTERNATIVE_GCC_LIBS) && $(HAIKU_ALTERNATIVE_GCC_OUTPUT_DIR) {
		partialName = $(partialName)hybrid ;
	}
} else {
	partialName = $(TARGET_ARCH) ;
}

# These are the actual build profiles.
#
# Install directly to a partition.
# See /guides/building/jam#sudo_jam.
DefineBuildProfile walter-sda2 : disk : "/dev/sda2" ;
# Install to container files. 
#     image, which can be `dd` to disk or used with Qemu
#     vmware-image, exclusively for VMWare or can be converted for VirtualBox
DefineBuildProfile walter-raw : image : "walter-$(partialName).image" ;
DefineBuildProfile walter-vmware : vmware-image : "walter-$(partialName).vmdk" ;
DefineBuildProfile bare-raw : image : "bare-$(partialName).image" ;
DefineBuildProfile bare-vmware : vmware-image : "bare-$(partialName).vmdk" ;

# This switch statement allows you to define settings for each build profile.
#
switch $(HAIKU_BUILD_PROFILE) {
	case "walter-*" : {
		HAIKU_ROOT_USER_NAME = walter ;
		HAIKU_ROOT_USER_REAL_NAME = "Walter TheFish" ;
		AddGroupToHaikuImage party : 101 : user sshd ;
		HAIKU_IMAGE_HOST_NAME = fishbowl ;
		HAIKU_IMAGE_SIZE = 600 ;

		Echo Building Walter for $(HAIKU_ROOT_USER_NAME) ;
		
		AddOptionalHaikuImagePackages BePDF Firefox Pe Vision VLC WonderBrush ;
		AddOptionalHaikuImagePackages CVS Development Subversion OpenSSH ;
		AddOptionalHaikuImagePackages Welcome BeBook ;
		AddOptionalHaikuImagePackages BeHappy Nano P7zip Python Rsync Tar ;
		AddFilesToHaikuImage common bin : diff_zip ;

		# Set the defaults for timezone and keymap:
		#
		AddSymlinkToHaikuImage home config settings
			: /boot/system/etc/timezones/Europe/Paris : timezone ;
		AddFilesToHaikuImage home config settings : <keymap>German 
			: Key_map ;

		# Zip up your emails between each system update and place the archive into the
		# user_data folder to be automatically put back when building the new image.
		# 
		UnzipArchiveToHaikuImage home
			: $(HAIKU_TOP)/user_data/mail.zip ;
	}
	
	case "bare-*" : {
		HAIKU_ROOT_USER_NAME = walter ;
		HAIKU_ROOT_USER_REAL_NAME = "Walter TheFish" ;
		AddGroupToHaikuImage party : 101 : user sshd ;
		HAIKU_IMAGE_HOST_NAME = fishbowl ;
		HAIKU_IMAGE_SIZE = 300 ;

		Echo Building Walter-barebones for $(HAIKU_ROOT_USER_NAME) ;

		AddOptionalHaikuImagePackages BePDF Links Nano Vision ;
		AddOptionalHaikuImagePackages Development Subversion OpenSSH ;
		AddFilesToHaikuImage common bin : diff_zip ;
	}
}

For example, the pre-alpha build profile as defined in ReleaseBuildProfiles, is invoked with

jam -q @alpha-raw