compile-project - SKILL.md Agent Skill

name: compile-project description: Compile the Blockscout Elixir project to verify all dependencies and code changes work correctly. Use this skill before finalizing changes to ensure the project builds successfully without errors.

Overview

The compile-project skill ensures that all Elixir code, dependencies, and configurations in the Blockscout project compile successfully. This is a critical verification step before committing changes or submitting pull requests.

When to Use

Before committing code changes - Verify your changes don't break compilation
After modifying dependencies - Ensure all deps resolve correctly
After significant refactoring - Validate code structure changes
Before creating a pull request - Final verification that everything builds
After pulling updates - Ensure your local environment is in sync
When fixing compilation errors - Iterative testing during debugging
After adding new modules or functions - Verify project-wide compatibility

How to Compile

Run the following command from the workspace root:

mix do deps.get, local.hex --force, local.rebar --force, deps.compile, compile

Command Breakdown

mix do - Executes multiple Mix tasks in sequence
deps.get - Fetches all project dependencies from Hex and Git
local.hex --force - Installs/updates Hex (package manager), forcing reinstall
local.rebar --force - Installs/updates Rebar (Erlang build tool), forcing reinstall
deps.compile - Compiles all dependencies
compile - Compiles the project itself

Dependencies-Only Compilation

If you only need to compile dependencies without the project code:

mix do deps.get, local.hex --force, local.rebar --force, deps.compile

Example Usage

After Making Code Changes

mix do deps.get, local.hex --force, local.rebar --force, deps.compile, compile

Expected Output

Successful compilation will show:

* Getting dependencies...
* Compiling dependencies...
==> dependency_name
Compiling X files (.ex)
Generated dependency_name app
...
==> blockscout
Compiling X files (.ex)
Generated blockscout app

Common Errors and Solutions

1. Dependency Lock Mismatch

** (Mix) You have changed mix.exs but mix.lock is out of date

Solution:

mix deps.get

2. Stale Build Artifacts

** (CompileError) cannot compile dependency

Solution:

mix deps.clean --all
mix do deps.get, local.hex --force, local.rebar --force, deps.compile, compile

3. Compilation Warnings

warning: variable "foo" is unused

Action: Fix unused variables or prefix with underscore _foo

Integration with Development Workflow

Recommended Pre-Commit Checklist

✅ Run mix format - Fix formatting issues
✅ Run mix do deps.get, local.hex --force, local.rebar --force, deps.compile, compile - Verify compilation
✅ Run mix test - Execute test suite (if applicable)
✅ Run mix credo - Check code quality (if available)
✅ Review git diff - Confirm changes are intentional
✅ Commit and push

Quick Verification After Changes

# Format, compile, and verify in one go
mix format && mix do deps.get, local.hex --force, local.rebar --force, deps.compile, compile

Performance Notes

First compilation: Can take several minutes (downloads and compiles all dependencies)
Incremental compilation: Usually seconds to minutes (only changed files)
Clean compilation: Use mix clean or mix deps.clean --all when needed
Parallel compilation: Mix automatically uses available CPU cores

When Compilation Warnings Are Acceptable

Some warnings may be acceptable in certain contexts:

TODO comments - Tracked technical debt
Unused variables in generated code - Auto-generated functions
Module redefinition warnings - Configuration loading order (like ConfigHelper)

However, new code should aim for zero warnings.

Troubleshooting

Dependencies Won't Compile

# Nuclear option: clean everything and start fresh
rm -rf _build deps
mix do deps.get, local.hex --force, local.rebar --force, deps.compile, compile

Erlang/Elixir Version Mismatch

Check required versions in mix.exs:

def project do
  [
    elixir: "~> 1.19",
    # ...
  ]
end

Verify your versions:

elixir --version

Permission Issues with Rebar

If mix local.rebar --force fails with permission errors, ensure proper ownership and permissions:

# Fix ownership of Mix home directory
chown -R $(whoami) ~/.mix ~/.hex $MIX_HOME $HEX_HOME 2>/dev/null || true

# Or explicitly set Mix/Hex home directories if needed
export MIX_HOME=~/.mix
export HEX_HOME=~/.hex

# Then try again
mix local.rebar --force

Note: Running Mix as root (with sudo) is strongly discouraged as it commonly causes permission/ownership issues in _build, deps, and ~/.mix. It can also create security/operational risks. Use proper file ownership and environment variables instead.

CI/CD Integration

This compilation step is typically part of the CI/CD pipeline. Ensure your changes pass locally before pushing to avoid CI failures.

Related Skills

code-formatting - Format code before compilation
compare-against-empty-list - Fix performance issues that might surface during compilation

Key Takeaways

Always compile before committing - Catch errors early
Use the full command - Ensures dependencies are up-to-date
Monitor compilation warnings - They often indicate real issues
Clean builds when in doubt - Removes stale artifacts
Compilation success ≠ correctness - Still need tests and manual verification
Fast feedback loop - Run frequently during development
Avoid running Mix as root - Use proper permissions instead

Additional Commands

Check for unused dependencies

mix deps.unlock --unused

View dependency tree

mix deps.tree

Compile with warnings as errors (strict mode)

mix compile --warnings-as-errors