Julia Package Development

Use this skill when working with Julia packages to ensure proper development workflows, testing patterns, documentation standards, and performance best practices.

Development Workflow

Environment Management

# Start Julia with project environment
julia --project=.

# Activate project in REPL
using Pkg
Pkg.activate(".")

# Install dependencies
Pkg.instantiate()

# Update dependencies (PREFERRED over direct Project.toml editing)
Pkg.update()

# Add new dependency
Pkg.add("PackageName")

# Add development dependency
Pkg.add("PackageName"; io=devnull)  # Then manually move to extras/test deps

# Check package status
Pkg.status()

IMPORTANT: Always use Pkg.update() to update packages. Never edit Project.toml directly for version updates.

Testing

# Run all tests (from project root)
julia --project=. -e 'using Pkg; Pkg.test()'

# Run tests with test environment
julia --project=test test/runtests.jl

# Run tests skipping quality checks (if supported)
julia --project=test test/runtests.jl skip_quality

Test Organization:

Use TestItemRunner with @testitem syntax for modular testing
Organize tests by component: test/component/, test/package/
Package-level tests in test/package/ for quality (Aqua, DocTest, formatting)
Use @testitem "description" begin ... end for individual test items

Example test structure:

using TestItemRunner

@testitem "Basic functionality" begin
    using MyPackage
    @test my_function(1) == 2
end

@testitem "Edge cases" begin
    using MyPackage
    @test_throws ArgumentError my_function(-1)
end

Documentation

# Build documentation locally
julia --project=docs docs/make.jl

# Build docs skipping notebooks (faster)
julia --project=docs docs/make.jl --skip-notebooks
# or via environment variable
SKIP_NOTEBOOKS=true julia --project=docs docs/make.jl

# Start Pluto server for interactive notebooks
# (check project-specific task or command)

Documentation Structure:

Use Documenter.jl for documentation
Auto-deployment to GitHub Pages via CI
Structure defined in docs/pages.jl or docs/make.jl

Code Quality

# Run pre-commit hooks
pre-commit run --all-files

# JuliaFormatter (typically configured in .JuliaFormatter.toml)
# Usually handled by pre-commit hooks

Quality Checks:

Aqua.jl tests for package quality
JuliaFormatter.jl for code formatting
Pre-commit hooks for automated checks

Code Style Guidelines

SciML Coding Standards

Follow SciML (Scientific Machine Learning) coding standards:

Avoid type instability
Ensure efficient precompilation
Use appropriate type annotations for performance
Write type-stable code

Type Stability:

# Good - type stable
function compute(x::Float64)
    result = 0.0  # Type is known
    for i in 1:10
        result += x * i
    end
    return result
end

# Avoid - type unstable
function compute_bad(x)
    result = 0  # Type might change
    for i in 1:10
        result = result + x * i  # Type may vary
    end
    return result
end

Formatting Rules

Max 80 characters per line
No trailing whitespace
No spurious blank lines
Use JuliaFormatter.jl for consistent formatting

Documentation Standards

Docstring Syntax

Use @doc with either raw strings or regular strings:

# For simple docstrings without LaTeX or templates
@doc "
Brief description of the function.

# Arguments
- `x`: Description of x
- `y`: Description of y

# Returns
- Description of return value

# Examples
```jldoctest
julia> my_function(1, 2)
3

" function my_function(x, y) return x + y end

For docstrings with LaTeX math

@doc raw" Computes the mathematical function:

f(x) = \int_0^x t^2 dt

Use raw strings when including LaTeX to preserve backslashes. " function math_function(x) # implementation end


### DocStringExtensions Templates

**IMPORTANT**: Template expansion rules:
- Use `@doc "` (regular string) for templates (allows expansion)
- Use `@doc """` with escaped backslashes when combining templates with LaTeX
- **NEVER** use `@doc raw"` with templates (prevents expansion)

```julia
using DocStringExtensions

# Good - template will expand
@doc "
$(TYPEDSIGNATURES)

Brief description.

# Fields
$(TYPEDFIELDS)
"
struct MyType
    "Field description"
    field::Int
end

# Good - template + LaTeX with escaped backslashes
@doc """
\$(TYPEDSIGNATURES)

Computes: ``f(x) = \\int_0^x t^2 dt``

Note the escaped backslashes in LaTeX: \\int, not \int
"""
function combined_function(x)
    # implementation
end

# Avoid - raw string prevents template expansion
@doc raw"
$(TYPEDSIGNATURES)  # This will NOT expand!
"

Documentation Structure Best Practices

Keep interface method docstrings concise (1-2 lines)
Use "See also" sections for cross-references
Avoid duplication between related functions (pdf/logpdf, cdf/logcdf)
Include mathematical formulations in main type/constructor docstrings
Provide minimal but sufficient examples using @example blocks

Cross-referencing:

@doc "
Compute the cumulative distribution function.

See also: [`logcdf`](@ref)
"
function cdf(d::MyDist, x::Real)
    # implementation
end

@doc "
Compute the log cumulative distribution function.

See also: [`cdf`](@ref)
"
function logcdf(d::MyDist, x::Real)
    # implementation
end

Package Structure

Typical Julia package structure:

MyPackage.jl/
├── src/
│   ├── MyPackage.jl        # Main module file with exports
│   ├── component1.jl       # Component implementations
│   ├── component2.jl
│   ├── docstrings.jl       # DocStringExtensions templates
│   └── utils/
├── test/
│   ├── runtests.jl         # Main test file
│   ├── component1/         # Tests by component
│   ├── component2/
│   └── package/            # Quality tests (Aqua, formatting)
├── docs/
│   ├── make.jl             # Documentation build script
│   ├── src/                # Documentation source
│   └── pages.jl            # Page structure (optional)
├── Project.toml            # Package dependencies
└── README.md

Performance Best Practices

Type Stability

# Check type stability with @code_warntype
@code_warntype my_function(args...)

# Look for red (Any) types - indicates type instability

Precompilation

# Ensure efficient precompilation
# Use PrecompileTools.jl for complex packages
using PrecompileTools

@compile_workload begin
    # Representative workload for precompilation
    my_function(example_args...)
end

Performance Patterns

Use in-place operations when possible (! suffix convention)
Preallocate arrays for loops
Use @simd, @inbounds when safe
Consider StaticArrays.jl for small fixed-size arrays
Profile with @time, @benchmark (BenchmarkTools.jl)

Common Dependencies and Patterns

Distributions.jl Interface

When implementing distributions:

Implement required methods: pdf, logpdf, cdf, logcdf, quantile, rand
Implement support methods: minimum, maximum, insupport
Optionally implement: mean, var, std (if analytically tractable)
Vectorization handled automatically via broadcasting
Consider specialized batch methods: pdf!, logpdf!, cdf!

Turing.jl and AD Compatibility

Ensure compatibility with automatic differentiation:

ForwardDiff.jl
ReverseDiff.jl
Zygote.jl
Enzyme.jl

Avoid non-differentiable operations in AD-sensitive code.

Common Julia Ecosystem Tools

Pkg: Package management
TestItemRunner: Modern testing framework
Documenter.jl: Documentation generation
DocStringExtensions: Documentation templates
JuliaFormatter.jl: Code formatting
Aqua.jl: Package quality testing
BenchmarkTools.jl: Performance benchmarking
PrecompileTools.jl: Precompilation optimization

When to Use This Skill

Activate this skill when:

Developing Julia packages
Writing Julia tests
Documenting Julia functions
Setting up Julia package infrastructure
Working with Distributions.jl, Turing.jl, or SciML packages
Optimising Julia code performance

This skill provides Julia-specific development patterns. Project-specific architecture and domain knowledge should remain in project CLAUDE.md files.

julia-development