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