Skip to content

permissive.md

Latest commit

 

History

History
210 lines (163 loc) · 5.48 KB

permissive.md

File metadata and controls

210 lines (163 loc) · 5.48 KB

🎛️ Permissive Mode

Permissive Mode gives you explicit control over workspace discovery and program exclusions. Perfect for multi-workspace repositories and complex build scenarios.

Overview

Permissive mode provides fine-grained control:

  • Multi-workspace support - specify multiple Cargo.toml workspaces
  • Flexible denials - deny programs by pattern
  • Global + local denials - apply denials across all workspaces or per-workspace
  • Explicit configuration - everything is specified, nothing is assumed

Basic Configuration

[package.metadata.elf-magic]
mode = "permissive"
workspaces = [
    { manifest_path = "./Cargo.toml" }
]

Advanced Configuration

With Exclusions

[package.metadata.elf-magic]
mode = "permissive"
workspaces = [
    { manifest_path = "./Cargo.toml", deny = ["target:test*", "package:dev*"] },
    { manifest_path = "examples/basic/Cargo.toml", deny = ["target:*_example"] }
]

With Global Exclusions

[package.metadata.elf-magic]
mode = "permissive"
global_deny = ["package:apl-token", "target:*_test"] 
workspaces = [
    { manifest_path = "./Cargo.toml", deny = ["target:dev*"] },
    { manifest_path = "examples/Cargo.toml" }
]

Exclusion Patterns

Permissive mode supports three pattern types:

Target Patterns

Match against the target name (what becomes the constant):

deny = ["target:test*", "target:*_example", "target:benchmark_*"]

Package Patterns

Match against the package name:

deny = ["package:dev*", "package:*-test", "package:example-*"]

Path Patterns

Match against the manifest path:

deny = ["path:*/examples/*", "path:*/tests/*", "path:*/benchmarks/*"]

Pattern Syntax

  • * - matches any number of characters
  • ? - matches a single character
  • Standard glob patterns supported

Global vs Local Exclusions

Global Exclusions

Applied to all workspaces:

global_deny = ["package:*-test", "target:bench*"]

Local Exclusions

Applied to specific workspace:

{ manifest_path = "./Cargo.toml", deny = ["target:dev*"] }

Merging Behavior

Global and local exclusions are merged for each workspace:

  • Global: ["package:*-test"]
  • Local: ["target:dev*"]
  • Effective: ["package:*-test", "target:dev*"]

Field Aliases

Both field names are supported for flexibility:

# These are equivalent:
{ manifest_path = "./Cargo.toml", deny = ["target:test*"] }
{ manifest_path = "./Cargo.toml", exclude = ["target:test*"] }

Multi-Workspace Example

Perfect for projects like Arch Network (main workspace + examples):

[package.metadata.elf-magic]
mode = "permissive"
global_deny = ["package:*-test", "target:bench*"]
workspaces = [
    { manifest_path = "./Cargo.toml", deny = ["target:example*"] },
    { manifest_path = "examples/basic/Cargo.toml", deny = ["target:*_demo"] },
    { manifest_path = "examples/advanced/Cargo.toml" },
    { manifest_path = "tests/integration/Cargo.toml", deny = ["path:*/integration/*"] }
]

Build Output

Permissive mode shows detailed exclusion information:

$ cargo build
Mode: permissive (3 workspaces specified)

Workspace: ./Cargo.toml
  + token_manager
  + governance
  - test_program (denied by pattern)
- benchmark_suite (denied by pattern)

Workspace: examples/basic/Cargo.toml
  + swap_example
  - basic_demo (denied by pattern)

Generated constants with 3 Solana programs

When to Use Permissive Mode

✅ Perfect for:

  • Multi-workspace repositories
  • Projects with test/example programs to exclude
  • Complex monorepos (like Anza/Agave with 50+ programs)
  • Production builds needing specific exclusions
  • When you need explicit control over what gets built

❌ Overkill for:

  • Simple single-workspace projects
  • Quick prototyping
  • When you want all programs included

Workspace Structure

Typical multi-workspace setup:

arch-network/
├── Cargo.toml                    # Main workspace
├── elves/
│   ├── build.rs                  # elf_magic::build().unwrap();
│   └── Cargo.toml                # Permissive config
├── programs/                     # Main programs
│   ├── orderbook/
│   ├── apl-token/               # Excluded via global_deny
│   └── governance/
└── examples/                     # Separate workspaces
    ├── basic/
    │   └── Cargo.toml            # Independent workspace
    └── advanced/
        └── Cargo.toml            # Another independent workspace

Error Handling

Missing Workspaces Field

[package.metadata.elf-magic]
mode = "permissive"
# Missing workspaces field - will error

Error: Invalid elf-magic config: missing field 'workspaces'

Invalid Patterns

Invalid patterns are warned about but don't fail the build:

Warning: Invalid deny pattern 'invalid-pattern'. Use 'target:', 'package:', or 'path:' prefix.

Troubleshooting

Workspace not found

Error: Failed to obtain package metadata
Solution: Verify manifest_path points to valid Cargo.toml

Unexpected exclusions

Use verbose patterns and check global vs local exclusions are correctly configured.

No programs included

If all programs are excluded, you'll get empty generated constants with warning.

Next Steps: