Modules



hof mod helps you manage CUE modules and dependencies. They are based on Go modules, can be backed by git or oci, support public and private visibility, and make working with CUE modules easy!



A CUE module is a collection of packages and is recognized by a cue.mod/module.cue file containing a module: "github.com/org/repo" field. The modules and packages work like other languages, allowing you to organize your code and later import it elsewhere. CUE is already module aware but lacks dependency management. hof mod fills that gap to make working with modules easy.

hof mod is based on Go modules, so you will recognize both the commands and the dependency file. In fact, hof reuses much of the algorithm. The main difference is the file location and format. Another notable difference is that hof has no global servers or registries, and instead talks directly to the code host to avoid adding more middlemen in your software supply chain.

A brief introduction is below while the following pages go into detail.


Module Layout
Authentication

Creating a Module

To create a new module, run hof mod init <module-path>. This will create a cue.mod/module.cue If you have already manually made the cue.mod/module.cue file, then you can skip this step.

hof mod init github.com/hofstadter-io/hof

It is best to use the same path as the Git repository. This makes your code immediately reuseable by pushing commits or a semver tag.

module: "github.com/hofstadter-io/hof"
cue: "0.6.0"

require:  { ... } // your dependencies
indirect: { ... } // dependency-dependencies
replace:  { ... } // replaces during development

Adding a Dependency

Use hof mod get to add and fetch a new dependency. Hof recogonizes semver tags, several special version names, and allows for any commit hash.

hof mod get github.com/hofstadter-io/hof@v0.6.8
hof mod get github.com/hofstadter-io/hof@v0.6.8-beta.6
hof mod get github.com/hofstadter-io/hof@latest   // latest semver
hof mod get github.com/hofstadter-io/hof@next     // next prerelease
hof mod get github.com/hofstadter-io/hof@main     // latest commit on branch
hof mod get github.com/hofstadter-io/hof@475328015adf6d102e5227a646e63f6a2b23119f

Updating Dependencies

Use hof mod tidy to inspect your imports, update the dependency list, and fetch any missing modules. This command will update both module.cue and sums.cue, which is used to store module hashes. You can verify code integrity later by running hof mod verify.

You can update dependency versions with hof mod get

  • hof mod get <module-path>@latest or @next for a prerelease
  • hof mod get all@latest to update all dependencies to their most recent version

Fetching Dependencies

Hof supports two methods for fetching dependencies into your project.

  1. hof mod vendor will copy the files into cue.mod/pkg/...
  2. hof mod link will symlink the directories into cue.mod/pkg/...

The choice can depend on personal preference or system requirements. (Windows does not support symlinks) Linking makes co-development with local replaces easier, as changes are automatic and do not require you to run hof mod vendor to get updates from another directory.


$ hof mod help

hof mod is CUE dependency management based on Go mods.

### Module File

The module file holds the requirements for project.
It is found in cue.mod/module.cue	

---
// These are like golang import paths
//   i.e. github.com/hofstadter-io/hof
module: "<module-path>"
cue: "v0.5.0"

// Required dependencies section
require: {
  // "<module-path>": "<module-semver>"
  "github.com/hofstadter-io/ghacue": "v0.2.0"
  "github.com/hofstadter-io/hofmod-cli": "v0.8.1"
}

// Indirect dependencies (managed by hof)
indirect: { ... }

// Replace dependencies with local or remote
replace: {
  "github.com/hofstadter-io/ghacue": "github.com/myorg/ghacue": "v0.4.2"
  "github.com/hofstadter-io/hofmod-cli": "../mods/clie"
}
---


### Authentication and private modules

hof mod prefers authenticated requests when fetching dependencies.
This increase rate limits with hosts and supports private modules.
Both token and sshkey base methods are supported, with preferences:

1. Matching entry in .netrc
  machine github.com
  login github-token
  password <github-token-value>

2. ENV VARS for well known hosts.

  GITHUB_TOKEN
  GITLAB_TOKEN
  BITBUCKET_USERNAME / BITBUCKET_PASSWORD or BITBUCKET_TOKEN 

  The bitbucket method will depend on the account type and enterprise license.

3. SSH keys 

  the following are searched: ~/.ssh/config, /etc/ssh/config, ~/.ssh/id_rsa


### Usage

there are two main commands you will use, init & tidy

# Initialize the current folder as a module
hof mod init <module-path>     (like github.com/org/repo)

# Refresh dependencies, discovering any new imports
hof mod tidy

# Add a dependency
hof mod get github.com/hofstadter-io/hof@v0.6.8
hof mod get github.com/hofstadter-io/hof@v0.6.8-beta.6
hof mod get github.com/hofstadter-io/hof@latest   // latest semver
hof mod get github.com/hofstadter-io/hof@next     // next prerelease
hof mod get github.com/hofstadter-io/hof@main     // latest commit on branch

# Update dependencies
hof mod get github.com/hofstadter-io/hof@latest
hof mod get all@latest

# Symlink dependencies from local cache
hof mod link

# Copy dependency code from local cache
hof mod vendor

# Verify dependency code against cue.mod/sums.cue
hof mod verify

# This helpful output
hof mod help

Usage:
  hof mod [command]

Aliases:
  mod, m

Available Commands:
  clean       clean hof's module cache
  get         add a new dependency to the current module
  init        initialize a new module in the current directory
  link        symlink dependencies to cue.mod/pkg
  publish     publish a module
  tidy        recalculate dependencies and update mod files
  vendor      copy dependencies to cue.mod/pkg
  verify      verify integrity of dependencies

Flags:
  -h, --help   help for mod

Global Flags:
  -E, --all-errors           print all available errors
  -i, --ignore-errors        turn off output and assume defaults at prompts
  -D, --include-data         auto include all data files found with cue files
  -V, --inject-env           inject all ENV VARs as default tag vars
  -I, --input stringArray    extra data to unify into the root value
  -p, --package string       the Cue package context to use during execution
  -l, --path stringArray     CUE expression for single path component when placing data files
  -q, --quiet                turn off output and assume defaults at prompts
  -d, --schema stringArray   expression to select schema to apply to data files
      --stats                print generator statistics
  -0, --stdin-empty          A flag that ensure stdin is zero and does not block
  -t, --tags stringArray     @tags() to be injected into CUE code
  -v, --verbosity int        set the verbosity of output
      --with-context         add extra context for data files, usable in the -l/path flag

Use "hof mod [command] --help" for more information about a command.

Dependency Cache

hof mod fetches and copies module code into your system’s cache directory. This acts as a per-users, local module cache and helps reduce network requests and disk space. A module will only be fetched once on a system. You can find the cache directory in hof version and you can delete it with hof mod clean.

Note, Hofstadter does not run any proxies or sumdb and all requests go directly to the module host.