# How `make dev-install` Rebuilds Local Changes into the Agent's Cache

> Understand how make dev-install rebuilds local changes into the agent cache. Test your modifications instantly with the GO_MODERN_GUIDELINES_DEV environment variable.

- Repository: [JetBrains/go-modern-guidelines](https://github.com/jetbrains/go-modern-guidelines)
- Tags: how-to-guide
- Published: 2026-08-30

---

**The `make dev-install` workflow compiles the current checkout of go-modern-guidelines and places the resulting binary into a per-user cache directory, enabling instant testing of local modifications when the `GO_MODERN_GUIDELINES_DEV` environment variable is set to `1`.**

The **go-modern-guidelines** repository provides a developer-centric workflow for iterating on guideline implementations without disrupting the stable release. When you need to test changes to linting rules or internal logic, the `dev-install` target rebuilds your local source and injects the fresh binary into a cache that IDE agents can consume. This eliminates the need for full releases or manual binary swaps during active development.

## Overview of the Dev-Install Workflow

The workflow bridges your local Git checkout and the IDE agent runtime. Instead of installing a system-wide binary or modifying PATH variables, the mechanism writes the freshly built executable to a deterministic cache location. Agents that respect the `GO_MODERN_GUIDELINES_DEV` flag automatically prefer this cached build over the bundled release version.

This approach provides three distinct advantages:

- **Isolation**: The cached binary lives in user space (`$HOME/.cache` or `$XDG_CACHE_HOME`) without requiring elevated privileges.
- **Atomic updates**: The script uses temporary file creation followed by a rename operation, ensuring that running agents never see a partially written binary.
- **Instant feedback**: Re-running `make dev-install` after any code change immediately overwrites the cache, and subsequent agent invocations pick up the new version automatically.

## Step-by-Step Build Process

The `dev-install` workflow orchestrates environment detection, compilation, and atomic file placement through the interaction of the Makefile and the [`scripts/dev-install.sh`](https://github.com/JetBrains/go-modern-guidelines/blob/main/scripts/dev-install.sh) helper.

### Make Target Definition

The entry point resides in the Makefile at lines 18-20, which delegates to the shell script with the `install` argument:

```makefile
dev-install:
	@./scripts/dev-install.sh install

```

This indirection keeps the Makefile declarative while the shell script handles the imperative logic of environment setup and file operations.

### Cache Location Resolution

The script determines where to place the binary by checking standard environment variables. According to [`scripts/dev-install.sh`](https://github.com/JetBrains/go-modern-guidelines/blob/main/scripts/dev-install.sh) lines 8-12, it resolves the cache root using `$XDG_CACHE_HOME` or falls back to `$HOME/.cache/go-modern-guidelines` if the variable is unset. This adheres to the XDG Base Directory Specification while ensuring portability across macOS and Linux environments.

### Repository Root Detection

To ensure the build context is correct regardless of the current working directory, the script derives the repository root (`module_dir`) by traversing one directory up from its own location, as implemented in [`scripts/dev-install.sh`](https://github.com/JetBrains/go-modern-guidelines/blob/main/scripts/dev-install.sh) lines 22-24. This technique guarantees that `go build` executes against the project root containing `go.mod`, even if you invoke the script from a subdirectory.

### Binary Build Step

Inside the resolved module directory, the script executes a sanitized `go build` command with environment isolation. As shown in [`scripts/dev-install.sh`](https://github.com/JetBrains/go-modern-guidelines/blob/main/scripts/dev-install.sh) lines 39-41, it strips potential interference by setting `GOFLAGS=` and `GOWORK=off`, while disabling CGO via `CGO_ENABLED=0` to ensure a static, portable binary. The output writes to a temporary file named `<cache>/dev/go-modern-guidelines.tmp.$$`, where `$$` provides shell-level process isolation to prevent collisions during concurrent builds.

### Atomic Installation

After a successful compilation, the script performs an atomic filesystem operation. Per [`scripts/dev-install.sh`](https://github.com/JetBrains/go-modern-guidelines/blob/main/scripts/dev-install.sh) lines 42-45, the temporary file is renamed to `<cache>/dev/go-modern-guidelines`. This atomic move guarantees that any agent reading the binary path either sees the previous complete version or the new complete version, never a corrupted intermediate state. Upon completion, the script prompts you to `export GO_MODERN_GUIDELINES_DEV=1` to enable the dev build.

## How Agents Use the Cached Binary

IDE agents (such as the IntelliJ Go plugin) implement a version resolution protocol that checks the environment before launching the tool. When `GO_MODERN_GUIDELINES_DEV` is set to `1`, the agent bypasses the bundled release binary and instead executes the executable found at the cache location. This lookup occurs at runtime, meaning you can edit guideline source files in `internal/guidelines/`, rebuild with `make dev-install`, and immediately trigger the updated logic from within your IDE without restarting the plugin or the editor.

## Practical Usage Example

The following workflow demonstrates a complete development cycle, from initial cache population through iterative rebuilds:

```bash

# Build and install the local checkout into the cache

make dev-install

# Enable the dev binary for the current shell session

export GO_MODERN_GUIDELINES_DEV=1

# Run the tool (the agent will now pick up the cached binary)

go-modern-guidelines lint ./...

# After modifying sources (e.g., in internal/guidelines/), rebuild

make dev-install   # repeat whenever you change code

# When finished testing, remove the dev build

make dev-uninstall

```

## Key Source Files

Understanding the dev-install mechanism requires familiarity with these specific paths in the JetBrains/go-modern-guidelines repository:

- **`Makefile`** – Declares the `dev-install` and `dev-uninstall` targets that invoke the helper script.
- **[`scripts/dev-install.sh`](https://github.com/JetBrains/go-modern-guidelines/blob/main/scripts/dev-install.sh)** – Performs cache-directory resolution, builds the binary with isolated environment variables, and handles atomic installation/uninstallation.
- **`internal/guidelines/`** – Contains the guideline source implementations; edits here are reflected after rebuilding with `make dev-install`.

## Summary

- **`make dev-install`** triggers [`scripts/dev-install.sh`](https://github.com/JetBrains/go-modern-guidelines/blob/main/scripts/dev-install.sh) to build the current checkout and cache the binary locally.
- The cache resides at `$XDG_CACHE_HOME/go-modern-guidelines` or `$HOME/.cache/go-modern-guidelines`, ensuring per-user isolation.
- The build process uses `GOFLAGS= GOWORK=off CGO_ENABLED=0` to produce a clean, static binary written atomically to the cache.
- Setting **`GO_MODERN_GUIDELINES_DEV=1`** instructs agents to load the tool from the cache instead of the released version.
- Re-running the make target overwrites the cached binary, providing immediate feedback on code changes without plugin reloads.

## Frequently Asked Questions

### Where does `make dev-install` place the compiled binary?

The script writes the binary to a subdirectory of your user cache. Specifically, it checks `$XDG_CACHE_HOME` first; if undefined, it defaults to `$HOME/.cache/go-modern-guidelines/dev/go-modern-guidelines`. This location remains stable across reboots but is specific to your user account.

### Why does the build script unset `GOFLAGS` and `GOWORK`?

These environment variables are cleared to ensure a deterministic, reproducible build. Disabling workspaces (`GOWORK=off`) prevents the tool from accidentally compiling against local replace directives in your GOPATH, while clearing `GOFLAGS` removes any global build tags or compiler flags that might interfere with the standard compilation of the guideline tool.

### Do I need to restart my IDE after running `make dev-install`?

No. The agent checks the `GO_MODERN_GUIDELINES_DEV` environment variable at execution time. As long as your IDE process inherits the environment where `GO_MODERN_GUIDELINES_DEV=1` is exported, the next invocation of the tool will automatically read the fresh binary from the cache directory.

### How do I remove the development build and return to the stable release?

Execute `make dev-uninstall`, which invokes the same shell script with the uninstall argument. This removes the binary from the cache directory. Once the file is deleted, agents will fall back to the bundled release version regardless of the `GO_MODERN_GUIDELINES_DEV` setting.