Compile Project

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

1. mix do - Executes multiple Mix tasks in sequence
2. deps.get - Fetches all project dependencies from Hex and Git
3. local.hex --force - Installs/updates Hex (package manager), forcing reinstall
4. local.rebar --force - Installs/updates Rebar (Erlang build tool), forcing reinstall
5. deps.compile - Compiles all dependencies
6. 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

1. ✅ Run mix format - Fix formatting issues
2. ✅ Run mix do deps.get, local.hex --force, local.rebar --force, deps.compile, compile - Verify compilation
3. ✅ Run mix test - Execute test suite (if applicable)
4. ✅ Run mix credo - Check code quality (if available)
5. ✅ Review git diff - Confirm changes are intentional
6. ✅ 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