These install instructions assume you want to develop, build, and run the various Habitat software components in a Linux environment. The Habitat core team suggests that you use our consistent development environment that we call the "devshell" as the easiest way to get started.
- Install Docker for Mac
- Checkout the source by running
git clone [email protected]:habitat-sh/habitat.git; cd habitat - Run
maketo compile all Rust software components (this will take a while) - (Optional) Run
make testif you want to run the tests. This will take a while.
Everything should come up green. Congratulations - you have a working Habitat development environment.
You can enter a devshell by running make shell. This will drop you in a
Docker container at a Bash shell. The source code is mounted in under /src,
meaning you can use common Rust workflows such as cd components/sup; cargo build.
Note: The Makefile targets are documented. Run make help to show the
output (this target requires perl).
Optional: This project compiles and runs inside Docker containers so while
installing the Rust language isn't strictly necessary, you might want a local
copy of Rust on your workstation (some editors' language support require an
installed version). To install stable
Rust, run: curl -sSf https://sh.rustup.rs | sh. Additionally, the project maintainers use
rustfmt for code formatting. If
you are submitting changes, please ensure that your work has been run through
the latest version of rustfmt. An easy way to install it (assuming you have
Rust installed as above), is to run cargo install rustfmt and adding
$HOME/.cargo/bin to your PATH.
Note2: While this Docker container will work well for getting started with Habitat development, you may want to consider using a VM as you start compiling Habitat components. To do this, create a VM with your preferred flavor of Linux and follow the appropriate instructions for that flavor below.
These instructions assume you want to develop, build, and run the various
Habitat software components in a macOS environment. Components other than
the hab CLI itself aren't all supported on Mac, but it is sometimes useful
to run parts of the Habitat ecosystem without virtualization. We recommend
using another environment.
First clone the codebase and enter the directory:
git clone https://github.com/habitat-sh/habitat.git
cd habitat
Then, run the system preparation scripts and try to compile the project:
cp components/hab/install.sh /tmp/
sh support/mac/install_dev_0_mac_latest.sh
sh support/mac/install_dev_9_mac.sh
. ~/.profile
export PKG_CONFIG_PATH="/usr/local/opt/libarchive/lib/pkgconfig:/usr/local/opt/openssl/lib/pkgconfig:/usr/local/lib/pkgconfig:$PKG_CONFIG_PATH"
export IN_DOCKER=false
make
For the builds to find the libarchive and openssl libraries, you will need to
set the PKG_CONFIG_PATH environment variable as above before running cargo build, cargo test, etc. Additionally to use the Makefile on Mac and not have
the tasks execute in the Docker-based devshell (see above), you will need to
set IN_DOCKER=false in your environment. If you use an environment switcher
such as direnv, you can set up the following in the root
of the git repository:
echo 'export PKG_CONFIG_PATH="/usr/local/opt/libarchive/lib/pkgconfig:/usr/local/opt/openssl/lib/pkgconfig:/usr/local/lib/pkgconfig:$PKG_CONFIG_PATH"' > .envrc
direnv allow
This installation method uses as many packages from Ubuntu as possible. This will closely reproduce the state of the Docker-based "devshell" as it also uses an Ubuntu base image.
First clone the codebase and enter the directory:
git clone https://github.com/habitat-sh/habitat.git
cd habitat
Then, run the system preparation scripts and try to compile the project:
cp components/hab/install.sh /tmp/
sh support/linux/install_dev_0_ubuntu_latest.sh
sh support/linux/install_dev_9_linux.sh
. ~/.profile
make
These docs were tested with Ubuntu 16.04 and 16.10 VMs.
This can be used to build and install on older versions of Ubuntu where libsodium and czmq aren't available.
First clone the codebase and enter the directory:
git clone https://github.com/habitat-sh/habitat.git
cd habitat
Then, run the system preparation scripts and try to compile the project:
cp components/hab/install.sh /tmp/
sh support/linux/install_dev_0_ubuntu_14.04.sh
sh support/linux/install_dev_9_linux.sh
. ~/.profile
make
These docs were tested with a Docker image, created as follows:
docker run --rm -it ubuntu:trusty bash
apt-get update && apt-get install -y sudo git-core
useradd -m -s /bin/bash -G sudo jdoe
echo jdoe:1234 | chpasswd
sudo su - jdoe
First clone the codebase and enter the directory:
git clone https://github.com/habitat-sh/habitat.git
cd habitat
Then, run the system preparation scripts and try to compile the project:
cp components/hab/install.sh /tmp/
sh support/linux/install_dev_0_centos_7.sh
sh support/linux/install_dev_9_linux.sh
. ~/.profile
make
If you have issues with libsodium at runtime, ensure that you've set
LD_LIBRARY_PATH and PKG_CONFIG_PATH:
export LD_LIBRARY_PATH=/usr/local/lib
export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig
These docs were tested with a Docker image, created as follows:
docker run --rm -it centos:7 bash
yum install -y sudo git
useradd -m -s /bin/bash -G wheel jdoe
echo jdoe:1234 | chpasswd
sudo su - jdoe
First clone the codebase and enter the directory:
git clone https://github.com/habitat-sh/habitat.git
cd habitat
Then, run the system preparation scripts and try to compile the project:
cp components/hab/install.sh /tmp/
sh support/linux/install_dev_0_arch.sh
sh support/linux/install_dev_9_linux.sh
. ~/.profile
make
These docs were tested with a Docker image, created as follows:
docker run --rm -it greyltc/archlinux bash
pacman -Syy --noconfirm
pacman -S --noconfirm sudo git
echo "%wheel ALL=(ALL) ALL" > /etc/sudoers.d/01_wheel
useradd -m -s /bin/bash -G wheel jdoe
echo jdoe:1234 | chpasswd
sudo su - jdoe
While the available docker images can provide a convenient contributor onboarding experience, they may not prove ideal for extensive habitat development. Building habitat components is a disk intensive operation. Mounted file systems across network boundaries, even when confined to a single local host, can yield build times dramatically slower than building against a locally attached file system. Build times will be best on either a bare metal linux environment or a dedicated linux vm. Also note that when using vagrant to provision a vm for habitat development, it is advised that you do not put your habitat repo on a synced folder or at least do not use that folder as your build target.
The following directions clone the habitat repository into a local directory to realize faster build times; however, while faster, this approach carries the risk of losing your work if your VM should crash or get into an unrecoverable state. If developing in a VM, intermittently pushing a WIP to your Habitat fork can protect your progress.
In the root of the project is a Vagrantfile that provisions an Ubuntu environment for Habitat development:
vagrant up --provider virtualbox # See the Vagrantfile for additional providers and boxes
Feel free to use this file as a jumping-off point for customizing your own Habitat development environment.
vagrant ssh
sudo su -
git clone https://github.com/habitat-sh/habitat.git
cd habitat/components/builder-api
cargo test
These instructions are based on Windows 10 1607 (Anniversary update) or newer. Most of it will probably work downlevel.
All commands are in PowerShell unless otherwise stated. It is assumed that you
have git installed and configured. Posh-Git is a handy PowerShell module for
making git better in your PowerShell console (install-module posh-git).
# Clone the Habitat source
git clone https://github.com/habitat-sh/habitat.git
cd habitat
./build.ps1 components/hab -configure
-
Once make has finished, executables will exist in
/src/target/debug/foo, wherefoois the name of an executable (hab,hab-sup,hab-depot, etc). -
Executable names are specified in each components
Cargo.tomlfile in a TOML table like this:[[bin]] name = "hab-depot"
The -configure switch will make sure you have all the necessary dependencies to build the hab CLI tool, including Rust, the Visual Studio Build Tools, and all the native dependencies.
Not all crates have been fully ported to Windows.
Currently the hab command will build (as well as the dependent crates).
Work is in progress on the supervisor and other parts of the toolchain.
Run this command:
make bldr-run
When you are working on an individual component in the /components directory, you may wish to build, install, then use that individual component.
Let's say you want to do this with the supervisor (which lives in the components/sup directory).
Change directories into the component you want to build
cd components/sup
Then run
cargo build
Once it is finished compiling, you can find the new build in root hab_repo/target/debug
Head back to the root of the Habitat repo
cd ../..
And you will find your build in target/debug
If you built the sup component, this is where you would find the new build
target/debug/hab-sup
You can now run this newly built component with
./target/debug/hab-sup