Skip to content

Commit

Permalink
Re-organise FreeBSD documentation.
Browse files Browse the repository at this point in the history
  • Loading branch information
tmcgilchrist committed Sep 6, 2023
1 parent d68e0f3 commit a6a018d
Show file tree
Hide file tree
Showing 4 changed files with 23 additions and 28 deletions.
44 changes: 19 additions & 25 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,30 +4,21 @@
[![docs][docs-shield]][docs]
[![OCaml-CI Build Status][ocaml-ci-shield]][ocaml-ci]


OBuilder takes a build script (similar to a Dockerfile) and performs the steps in it in a sandboxed environment.

After each step, OBuilder uses the snapshot feature of the filesystem (ZFS or
Btrfs) to store the state of the build. There is also an Rsync backend that
copies the build state. On Linux, it uses `runc` to sandbox the build steps, but
any system that can run a command safely in a chroot could be used.
Repeating a build will reuse the cached results where possible.
After each step, OBuilder uses the snapshot feature of the filesystem (ZFS or Btrfs) to store the state of the build. There is also an Rsync backend that copies the build state. On Linux, it uses `runc` to sandbox the build steps, but any system that can run a command safely in a chroot could be used. Repeating a build will reuse the cached results where possible.

OBuilder can also use Docker as a backend (fully replacing of `runc` and the
snapshotting filesystem) on any system supported by Docker (Linux, Windows, …).
OBuilder can also use Docker as a backend (fully replacing of `runc` and the snapshotting filesystem) on any system supported by Docker (Linux, Windows, …).

OBuilder stores the log output of each build step.
This is useful for CI, where you may still want to see the output even if the result was cached from some other build.
OBuilder stores the log output of each build step. This is useful for CI, where you may still want to see the output even if the result was cached from some other build.

As present, the initial base image is fetched from Docker Hub using `docker pull` and then snapshotted into the store.
At present, the initial base image is fetched from Docker Hub using `docker pull` on Linux and then snapshotted into the store. Other systems use a conceptually similar process with the implementation in each platform section.

## Usage

OBuilder is designed to be used as a component of a build scheduler such as [OCluster][].
However, there is also a command-line interface for testing.
OBuilder is designed to be used as a component of a build scheduler such as [OCluster][]. However, there is also a command-line interface for testing.

To check that the system is working correctly, you can run a healthcheck.
This checks that Docker is running and then does a simple test build (pulling the `busybox` image if not already present):
To check that the system is working correctly, you can run a healthcheck. This checks that Docker is running and then does a simple test build (pulling the `busybox` image if not already present):

$ obuilder healthcheck --store=zfs:tank
Healthcheck passed
Expand Down Expand Up @@ -78,7 +69,7 @@ runc then sync operations will instead fail with `EPERM`.

## The build specification language

The spec files are loosely based on the [Dockerfile][] format.
The spec files are loosely based on the [Dockerfile]() format.
The main difference is that the format uses S-expressions rather than a custom format,
which should make it easier to generate and consume it automatically.

Expand All @@ -97,8 +88,7 @@ Example:
OBuilder will not check for updates, so `BASE` should include a digest identifying the exact image, as shown above.

The operations are performed in order. Each operation gets a build context and a filesystem snapshot, and may produce
a new context and a new snapshot.
The initial filesystem snapshot is `BASE`. `run` and `copy` operations create new snapshots.
a new context and a new snapshot. The initial filesystem snapshot is `BASE`. `run` and `copy` operations create new snapshots.

The initial context is supplied by the user (see [build.mli](https://github.com/ocurrent/obuilder/blob/master/lib/build.mli) for details).
By default:
Expand All @@ -113,12 +103,12 @@ You can define nested builds and use the output from them in `copy` operations.
For example:

((build dev
((from ocaml/opam:alpine-3.12-ocaml-4.11)
((from ocaml/opam:alpine-3.18-ocaml-5.0)
(user (uid 1000) (gid 1000))
(workdir /home/opam)
(run (shell "echo 'print_endline {|Hello, world!|}' > main.ml"))
(run (shell "opam exec -- ocamlopt -ccopt -static -o hello main.ml"))))
(from alpine:3.12)
(from alpine:3.18)
(shell /bin/sh -c)
(copy (from (build dev))
(src /home/opam/hello)
Expand All @@ -136,7 +126,8 @@ Example:
(workdir /usr/local)

This operation sets the current working directory used for the following commands, until the next `workdir` operation.
If the path given is relative, it is combined with the previous setting.
If the path given is relative, it is combined with the previous setting. **WARNING** Workdir implementation is idiosyncratic
on macOS, use with care.

### shell

Expand Down Expand Up @@ -248,7 +239,7 @@ Notes:
### user

(user (uid UID) (gid GID))
(user (name NAME)) ; on Windows
(user (name NAME)) ; on Windows and FreeBSD

Example:

Expand Down Expand Up @@ -283,10 +274,13 @@ The dockerfile should work the same way as the spec file, except for these limit
- All `(network …)` fields are ignored, as Docker does not allow per-step control of
networking.

## Experimental macOS and Windows Support
## Other Platforms

OBuilder abstracts over a fetching mechanism for the Docker base image, the sandboxing for the execution of build steps and the store for the cache.
This makes OBuilder extremely portable and there exists experimental macOS and Windows backends. The Windows backend currently requires Docker for Windows installed.
OBuilder abstracts over a fetching mechanism for the Docker base image, the sandboxing for
the execution of build steps and the store for the cache.
This makes OBuilder extremely portable and there exists FreeBSD, macOS and Windows backends.
The FreeBSD backend uses jails and ZFS, the macOS backend re-uses ZFS and user isolation, and
the Windows backend currently requires Docker for Windows installed.

## Licensing

Expand Down
File renamed without changes.
2 changes: 1 addition & 1 deletion doc/index.mld
Original file line number Diff line number Diff line change
Expand Up @@ -6,5 +6,5 @@ The entry point of this library is the module:
{1 Design and implementation of OBuilder}
- {{!page-README}OBuilder's manual}.
- {{!page-macOS}macOS implementation documentation}.
- {{!page-windows}Windows implementation documentation}.
- {{!page-freebsd}FreeBSD implementation documentation}.
- {{!page-windows}Windows implementation documentation}.
5 changes: 3 additions & 2 deletions dune
Original file line number Diff line number Diff line change
Expand Up @@ -6,12 +6,13 @@
(libraries lwt lwt.unix fmt fmt.cli fmt.tty tar-unix obuilder cmdliner logs.fmt logs.cli))

(rule
(targets README.mld macOS.mld windows.mld)
(deps README.md doc/macOS.md doc/windows.md)
(targets README.mld macOS.mld windows.mld freebsd.mld)
(deps README.md doc/macOS.md doc/windows.md doc/freebsd.md)
(action
(progn
(with-stdout-to README.mld (run md2mld README.md))
(with-stdout-to macOS.mld (run md2mld doc/macOS.md))
(with-stdout-to freebsd.mld (run md2mld doc/freebsd.md))
(with-stdout-to windows.mld (run md2mld doc/windows.md)))))

(copy_files doc/index.mld)
Expand Down

0 comments on commit a6a018d

Please sign in to comment.