Skip to content

Latest commit

 

History

History
162 lines (97 loc) · 7.16 KB

README.md

File metadata and controls

162 lines (97 loc) · 7.16 KB
Raw

Happy enVironment Manager

The Happy enVironment Manager (hvm) is similar to other tools, like nvm or rvm. It is meant to manage multiple installed versions of Happy and other software packages distributed by CZI via Github.

Each Happy project can create a .happy/version.lock JSON file, which specifies which versions of various packages the project requires. hvm can automatically install them and manage your path for you via zsh shell hooks or explicit CLI commands.

HVM is essentially a Github-based package manager, which installs CI/CD-produced assets directly from Github. It tries to be smart about architecture and operating system, and allows defaulting of specific versions for when a version is not otherwise specified (see set-default command).

Compatibility Notes

Operating Environments

This version of hvm was only tested on Mac and Linux. Behavior on Windows is currently unknown. It'll probably work under WSL2, but that has not been tested. Bug reports welcome, as always.

GitHub Projects

hvm communicates directly with Github, and parses tags, release names, and asset filenames in order to operate. It does not have a central registry or metadata file to rely on otherwise. This means that anything it must install must be set up very consistently with the way the chanzuckerberg/happy repo names version tags, releases, and release assets. It was primarily made to work with chanzuckerberg/happy, so that repo is the "reference implementation", for better or worse.

If this becomes a problem, we can likely introduce some sort of metadata file that can be generated by CI/CD in Github Actions which points things in the right direction, but for now, things just have to be named "correctly."

Github Quotas

Note that Github imposes request rate limits. For normal usage by individuals, this is not likely an issue. However, if this is to be used in CI/CD or automations, then quotas may quickly be reached. For now, hvm does not support the use of PATs or other auth to Github, so the anonymous hourly rate limits by IP address apply.

Quick Start

Common to all shells:

mkdir -p $HOME/.czi/bin $HOME/.czi/hooks

Install HVM on MacOS with Homebrew:

brew tap chanzuckerberg/tap
brew install hvm

For other OSs or without Homebrew, download appropriate hvm binaries from Github Releases for Happy project, and place in your $PATH. If you'd like, you can place it in $HOME/.czi/bin, as you'll be adding that to your $PATH next.

Set up your shell

First, make sure $HOME/.czi/bin is in your $PATH. Replace .zshrc with the appropriate rc file for your shell, if not using zsh.

echo 'export PATH=$HOME/.czi/bin:$PATH' >> $HOME/.zshrc

Installing the zsh Shell Hook

Prerequisites

  • You have installed hvm, and it is in your $PATH.
  • You are using zsh as your shell
  • oh-my-zsh is installed in your current shell.

Installation

  • Download the hvm-hooks.zsh file and place in $HOME/.czi/hooks
  • Add the following command to your $HOME/.zshrc:
source $($HOME/.czi/hooks/hvm-hooks.zsh)

Common Examples


# See available releases of a project:

hvm list-releases chanzuckerberg happy
hvm list-releases chanzuckerberg fogg
hvm list-releases chanzuckerberg aws-oidc

# Install a specific version of Happy, Fogg, or another CZI tool
# You should also uninstall any other copies you have on your
# system to avoid conflicts and confusion.

hvm install chanzuckerberg happy 0.127.0

# Make that version the default version when a specific 
# version is not specified, or you are outside a happy project

hvm set-default chanzuckerberg happy 0.127.0

# Lock a tool version while inside a Happy project
# These will be automatically pushed into your PATH when you
# enter the directory. If env var `HVM_AUTOINSTALL_PACKAGES=1`, 
# these will be auto-installed when you enter the directory.
# (See Environment Variables section below.)

hvm lock chanzuckerberg happy 0.127.0
hvm lock chanzuckerberg fogg 0.92.4

Subcommands

Note: Most commands require the following 2-3 parameters:

  • org: The GitHub org which owns the project (usually chanzuckerberg, but could be any other)
  • project: The repo name inside of the org (e.g. happy). Project must conform to hvm's established release/asset naming patterns.
  • version: The version of the package, which is the version tag minus the v.

help

Help is always available using the help command for hvm itself and each subcommand.

download

The download subcommand simply downloads the tarball for the requested package to the current directory or a path specified by -p or --path. It is generally meant for use in shell scripts where the default install behavior does not fit the use case.

You can specify the arch and os if you'd like to download binaries that are not for your current architecture or os. The default is to match the current arch/os.

Valid arch values: amd64 and arm64

Valid os values: linux, darwin, windows (see COMPATIBILITY note above)

env

The env command outputs shell commands intended to be evaled by your current shell:

eval $(hvm env)

This currently only manages $PATH, but may manage other things in the future.

It can be run explicitly as above, but is intended to be run via shell hooks each time your directory changes. This allows hvm to automatically manage your environment as specified by your Happy configurations.

install

The install command is used to download a package and extract it under .czi/versions/<org>/<project>/<version>. This is to allow for multiple concurrently-installed versions. This does NOT set your default version. See set-default to choose a default version.

list-releases

Get a list of available releases of a package.

lock

Create/update the locked version of a package in the current happy project. If you are not in a happy project, this will return an error.

set-default

Set a version of a package to be used when:

  • Outside of a Happy project
  • The current project does not contain a version.lock file
  • The version.lock file does not specify a version for a given package

This works by creating a symbolic link under $HOME/.czi/bin to the binary installed under a specific version of the package.

When inside a Happy project, hvm will prepend any specified versions to your $PATH, so they will supercede this default. If the project does not specify a version for a given package, or does not have a .happy/versions.lock file, there will be no match in your $PATH, and the path search will eventually fall back to $HOME/.czi/bin.

Environment Variables

Variable Values Purpose
HVM_AUTOINSTALL_PACKAGES unset or 1 Allow automatic installation of packages specified in project versions.lock files. Set to 1 to enable.
HVM_<ORG>_<PROJECT> Valid version number Override the version in versions.lock for a given org/project. Org and project names must be UPPERCASE. Example: export HVM_CHANZUCKERBERG_HAPPY=0.91.0