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

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

Safety Notice

Copy this and send it to your AI assistant to learn