# Working with Go modules

If you are not yet familiar with Go modules in general (outside of gokrazy), please read the Go wiki page on Modules first.

Since September 2022, the gokrazy packer builds each package in its own build directory, with its own `go.mod` and `go.sum` files. This is done for isolation: if you update one program, that will not have any effect on the other programs you include in your gokrazy instance.

## Example setup

Throughout this page, let’s assume your gokrazy instance is named `scanner`, and will hence store its files in `~/gokrazy/scanner`. A single additional program, `scan2drive`, is included:

    gok -i scanner new
    gok -i scanner add github.com/stapelberg/scan2drive/cmd/scan2drive

When building this instance (using `gok overwrite` initially, or `gok update` afterwards), the `gok` CLI will create the following build directory structure:

    % cd ~/gokrazy/scanner
    % find . -name go.mod
    ./builddir/init/go.mod
    ./builddir/github.com/stapelberg/scan2drive/cmd/scan2drive/go.mod
    ./builddir/github.com/gokrazy/serial-busybox/go.mod
    ./builddir/github.com/gokrazy/hello/go.mod
    ./builddir/github.com/gokrazy/fbstatus/go.mod
    ./builddir/github.com/gokrazy/gokrazy/go.mod
    ./builddir/github.com/gokrazy/gokrazy/cmd/randomd/go.mod
    ./builddir/github.com/gokrazy/gokrazy/cmd/ntp/go.mod
    ./builddir/github.com/gokrazy/gokrazy/cmd/dhcp/go.mod
    ./builddir/github.com/gokrazy/rpi-eeprom/go.mod
    ./builddir/github.com/gokrazy/firmware/go.mod
    ./builddir/github.com/gokrazy/kernel/go.mod

You can see that there is one subdirectory for each package listed in the `Packages` field of your instance’s `config.json` (see `gok edit`), which includes the explicitly added `scan2drive`, plus a couple extra ones that gokrazy always installs, e.g. `github.com/gokrazy/gokrazy/cmd/dhcp`.

## Top-level go.mod template

If you want to influence the content of any newly created `go.mod` (no effect on existing `go.mod` files), you can create a `go.mod` template in your instance directory: `~/gokrazy/scanner/go.mod`.

## Building local code: the replace directive

Go modules are loaded from the internet by default and are stored read-only on disk.

If you want to make the gokrazy packer pick up a local working copy with not-yet-published code, or a working copy with local changes to existing code, use `gok add` with a directory name:

    # Create a local working copy in whichever directory you like.
    % cd ~/projects
    % git clone https://github.com/stapelberg/scan2drive
    % cd scan2drive
    # make some changes

    % gok -i scan2drive add ./cmd/scan2drive

The `gok` CLI will set up the `replace` directive for you. For more details on `replace`, see the Go wiki.

To undo a local override, either manually delete the `replace` directive in the relevant `builddir/.../go.mod` file, or use `go mod edit` with `-dropreplace=path/to/pkg`. See this comment for a worked example.

## Influencing the granularity

Often, one Go package will be the only package you use from a certain Go module. But this isn’t always the case: for example, the system packages `github.com/gokrazy/gokrazy/cmd/dhcp` and `github.com/gokrazy/gokrazy/cmd/ntp` both come from the `github.com/gokrazy/gokrazy` module.

The packer will by default create a separate builddir, including a separate `go.mod` and `go.sum`, for each package, even when they come from the same module.

If you want to add module-wide replace directives to your `go.mod` file, you can influence the granularity at which gokr-packer works as follows.

Move the `go.mod`/`go.sum` files to the directory level within the `builddir/` hierarchy at which you would like to work. gokr-packer will look for `go.mod`/`go.sum` files at the package level, going one level up until it finds the files.

Hence, you can use the following locations, ordered from finest to coarsest granularity:

1. per-package builddir (default), e.g.: `builddir/github.com/gokrazy/gokrazy/cmd/dhcp/go.mod`

2. per-module builddir (convenient when working with replace directives), e.g.: `builddir/github.com/gokrazy/gokrazy/go.mod`

3. per-org builddir (convenient for wide-reaching replace directives), e.g.: `builddir/github.com/gokrazy/go.mod`

4. single builddir, preserving the previous behavior, e.g.: `builddir/go.mod`