A project by Petar Maymounkov.

App configuration: build, deploy, spawn

The circuit distribution comes with a simple build–deploy toolchain which is conveniently integrated with the runtime spawning mechanism. All three tasks—build, deploy, spawn—utilize a simple shared configuration file. This document is a reference for the format of this file.


The build system is embodied in the command 4crossbuild, the deploy system is embodied in 4deploy and the spawning mechanism is part of the user app's worker and command executables. All four types of executables use the same configuration file (which differs from application to application) and this file is supplied to all of them in the same manner—by pointing the environment variable CIR to that configuration file, before executing a command. For instance,

% CIR=app.config 4crossbuild
% CIR=app.config 4deploy < list_of_hosts
% CIR=app.config myapp_launch_cmd


The circuit configuration file must be presented in a valid JSON encoding. Below is a complete example of a circuit configuration file. The purpose of each field is explained afterwards.
	"Zookeeper": {
		"Workers":          ["z1.datacenter.net:2181", "z2.datacenter.net:2181"],
		"Dir":              "/circuit/myapp"
	"Deploy": {
		"Worker":           "myapp_worker_name"
		"Dir":              "/circuit/myapp",
	"Build": {
		"Host":             "build.datacenter.net",
		"Jail":             "/home/petar/build/myapp",
		"ZookeeperInclude": "/home/petar/gocircuit/misc/starter-kit-linux/zookeeper/include",
		"ZookeeperLib":     "/home/petar/gocircuit/misc/starter-kit-linux/zookeeper/lib",
		"CGO_CFLAGS":	    "-I/Users/petar/aux/leveldb/include",
		"CGO_LDFLAGS":      "/Users/petar/aux/leveldb/lib/libleveldb.a -lstdc++",		
		"Tool":             "/home/petar/gocircuit/bin/4build",
		"PrefixPath":       "/usr/local/bin",

		"AppRepo":          "{git}git@github.com:petar/circuit_myapp_project.git",
		"AppSrc":           "/GOPATH_relative_to_myapp_repo",

		"GoRepo":           "{hg}{tip}code.google.com/p/go",
		"RebuildGo":        false,

		"CircuitRepo":      "{hg}code.google.com/p/gocircuit",
		"CircuitSrc":       "/",

		"WorkerPkg":        "myapp_worker_pkg",
		"CmdPkgs":          ["cmd/myapp-spawn"],
		"ShipDir":          "/Users/petar/ship/myapp"


Field Zookeeper constitutes the “runtime” configuration of circuit workers. It specifies how to find the Zookeeper instance that coordinates all workers in this circuit's deployment. This part of the configuration file is used only by circuit executables (workers or command-line programs).


Field Deploy is utilized by (1) the build tool 4build, (2) the deploy tool 4deploy, as well as (3) the spawning mechanism at runtime. The build tool uses Deploy to determine how to name the resulting worker binary. The deploy tool uses Deploy to determine where within the file system of cluster hosts to install the circuit app binaries. Whereas, the spawning mechanism uses Deploy to find the installed worker binaries on a given host, when spawning a new worker.


Field Build is utilized only by the cross-build tool, 4crossbuild. It specifies how to build the worker executable of a circuit application. The cross-build tool is responsible for performing the actual build on a remote build host by essentially handing off all information in Build to the build tool, 4build, which runs locally on the remote build host. The information in field Build is exactly what 4build utilizes to complete a build. However, 4build itself does not use the configuration file. It receives all of its configuration on the command-line. This way it can be invoked both manually at the shell prompt as well as remotely through 4crossbuild.

Build server environment:

Application sources:

Go compiler:

Circuit sources: