nip/GRAFT_USE_FLAGS_INTEGRATION.md

Graft Command USE Flags Integration - Status

✅ Completed

1. Enhanced Graft Command Module

File: src/nimpak/cli/graft_commands_enhanced.nim

Features Implemented:

• Extended function signature to accept USE flags
• Parse USE flags from CLI (--use="+wayland -X +lto")
• Parse compiler flags from CLI (--cflags="-O3")
• Profile support (--profile=performance)
• USE flag resolution (profile → global → package → CLI)
• USE flag validation against categories
• Variant hash generation
• Display effective USE flags before grafting
• Display compiler flags
• Logging of USE flags and variants

Function Signature:

proc graftCommandWithUseFlags*(
  packageSpec: string,
  useFlagsStr: string = "",
  cflagsStr: string = "",
  profileName: string = "",
  verbose: bool = false,
  coordinator: GraftCoordinator
): int

2. USE Flag Processing Flow

1. Parse CLI USE flags
   ↓
2. Load configuration
   ↓
3. Get effective USE flags (merge: profile → global → package → CLI)
   ↓
4. Validate USE flags (check exclusive categories)
   ↓
5. Get effective compiler flags
   ↓
6. Generate variant hash
   ↓
7. Display settings to user
   ↓
8. Perform graft (with USE flags logged)
   ↓
9. Display results with variant info

3. Example Usage

# Basic graft with USE flags
nip graft firefox --use="+wayland -X +lto"

# With compiler flags
nip graft vim --use="+python +lua" --cflags="-O3 -march=native"

# Using a profile
nip graft nginx --profile=performance

# Nexus-specific flags
nip graft nexus-fleet --use="+fleet-agent +fleet-mesh +wireguard"

# Gaming with GPU acceleration
nip graft blender --use="+vulkan +rocm +amd +python"

# ML workstation
nip graft pytorch --use="+rocm +opencl +onnx +python"

4. Output Example

🌱 NIP Graft - Universal Package Grafting with USE Flags

🔧 CLI USE flags: +wayland -X +lto

Effective USE Flags:
===================
  Enabled:  +wayland +lto +ipv6 +ssl
  Disabled: -X

Compiler Flags:
==============
  CFLAGS:    -O3 -march=native -flto
  CXXFLAGS:  -O3 -march=native -flto
  LDFLAGS:   -Wl,-O1 -flto
  MAKEFLAGS: -j8

📦 Package: firefox
📍 Source: nix
🏷️  Variant: lto-wayland

✅ Graft successful!
📍 Installed to: /Programs/Firefox/120.0/
🏷️  Variant: lto-wayland
   (Variant tracking will be added to database in next update)
🔗 Symlinks created in /System/Links/

📋 Package built with USE flags:
   Enabled: +wayland +lto +ipv6 +ssl
   Disabled: -X

You can now run: firefox

⏳ TODO (Next Steps)

1. Main CLI Integration

Update nip_mvp.nim to parse --use, --cflags, --profile flags and call graftCommandWithUseFlags

2. Coordinator Enhancement

Update GraftCoordinator.graft() to accept and pass USE flags to adapters:

proc graft*(
  coordinator: GraftCoordinator,
  packageName: string,
  source: PackageSource,
  useFlags: seq[UseFlag] = @[],
  compilerFlags: CompilerFlags = CompilerFlags()
): UnifiedGraftResult

3. Adapter Enhancement

Update adapters to apply USE flags:

Nix Adapter:

# Map USE flags to Nix options
if hasUseFlag(useFlags, "wayland"):
  nixOptions.add("--arg waylandSupport true")
if hasUseFlag(useFlags, "X"):
  nixOptions.add("--arg x11Support true")

# Set compiler flags
putEnv("NIX_CFLAGS_COMPILE", compilerFlags.cflags)

PKGSRC Adapter:

# Map to PKG_OPTIONS
var pkgOptions: seq[string] = @[]
if hasUseFlag(useFlags, "wayland"):
  pkgOptions.add("wayland")
if not hasUseFlag(useFlags, "X"):
  pkgOptions.add("-x11")

4. Variant Management

Create variants.nim module:

proc generateVariantPath(name, version: string, useFlags: seq[UseFlag]): string
proc listVariants(packageName: string): seq[PackageVariant]
proc setDefaultVariant(packageName, variantHash: string): bool

5. Database Schema Update

Add fields to package database:

{
  "useFlags": [
    {"name": "wayland", "enabled": true, "category": "gui"},
    {"name": "lto", "enabled": true, "category": "optimization"}
  ],
  "useFlagsHash": "lto-wayland",
  "compilerFlags": {
    "cflags": "-O3 -march=native -flto",
    "cxxflags": "-O3 -march=native -flto"
  },
  "isDefaultVariant": true,
  "variantOf": "firefox-120.0"
}

6. CLI Commands

Implement:

• nip use <package> - Show/set USE flags
• nip profile <action> - Manage profiles
• nip variants <package> - List/manage variants

🎯 Integration Checklist

• Create enhanced graft command module
• Implement USE flag parsing
• Implement flag resolution
• Implement validation
• Implement variant hash generation
• Implement display functions
• Integrate with main CLI
• Update coordinator to pass USE flags
• Update adapters to apply USE flags
• Implement variant management
• Update database schema
• Implement USE/profile/variants commands
• Add tests
• Update documentation

📝 Notes

Current Limitations

• USE flags are parsed and displayed but not yet passed to adapters
• Variant paths are generated but not yet used for installation
• Database doesn't yet store USE flag metadata
• Multiple variants of same package not yet supported

Design Decisions

• USE flags follow Gentoo syntax (+flag, -flag)
• Resolution hierarchy: profile → global → package → CLI
• Variant hash uses sorted enabled flags only
• Exclusive categories validated before grafting
• Compiler flags can be overridden at any level

Testing Strategy

1. Unit tests for USE flag parsing ✅
2. Integration tests for flag resolution ✅
3. End-to-end tests for graft with USE flags ⏳
4. Adapter tests with USE flags ⏳
5. Variant management tests ⏳

🚀 Ready for Next Phase

The foundation is complete! USE flags are:

• ✅ Parsed correctly
• ✅ Resolved through hierarchy
• ✅ Validated against categories
• ✅ Displayed to users
• ✅ Logged for tracking

Next: Wire up to adapters and implement variant management.

---

Status: Phase 1 Complete (Graft Command Integration) Next: Phase 2 (Variant Management) Target: v0.2.0