Introduction

The ipm build command allows you to build a package from a source folder to a target folder. This is particularly useful when you want to inspect the package contents before publishing, ensuring that only the intended files are included and correctly organized.

Command Syntax 

ipm build -s <source-directory> [-d <destination-directory>] [--dry-run] [--include-manifest] [--summary-file <filepath>]

Required Parameters (option 1)

  • -s or --source: The source directory containing your package content
  • -d or --destination: The destination directory where the built package will be placed

Required Parameters (option 2)

  • -s or --source: The source directory containing your package content
  • --dry-run: Execute the build process without actually copying files, showing what would happen

Examples

Build package content from the current directory to a ‘dist’ folder:

ipm build -s ./ -d ./dist

Build a verified package with manifest generation:

ipm build -s ./my-package -d ./build-output --include-manifest

Preview what files would be included without actually building:

ipm build -s ./my-package --dry-run

Build package content from a specific source directory to another directory:

ipm build -s ./my-package -d ./preview

Build with comprehensive audit reporting:

ipm build -s ./my-package -d ./build-output --summary-file ./audit/build-report.json

Build a verified package with both manifest and audit reporting:

ipm build -s ./my-package -d ./build-output --include-manifest --summary-file ./audit/build-report.json

Verified Package Creation

Manifest Generation

The --include-manifest parameter enables the creation of verified packages by generating a comprehensive manifest file with cryptographic hashes:

ipm build -s ./my-package -d ./build-output --include-manifest

This creates a manifest file containing:

  • Individual File Hashes: SHA-256 hash for each file in the package
  • Complete Package Hash: Overall package integrity verification
  • File Inventory: Complete list of all files included
  • Metadata: Build timestamp and package structure details

Benefits of Verified Packages

  • Enterprise Security: Cryptographic proof of package integrity
  • Supply Chain Protection: Detection of unauthorized modifications
  • Compliance Assurance: Audit trail for regulatory requirements
  • Trust Verification: Visual verification badge for published packages

For complete details on verified packages, see the Verified Packages guide.

Audit Reporting

Summary File Generation

The --summary-file parameter creates detailed audit reports for compliance and governance:

ipm build -s ./my-package -d ./build-output --summary-file ./audit/build-report.json

Report Contents

Build audit reports include:

  • Operation Metadata: Action type, timestamps, and folder paths
  • File Processing: Complete list of processed files with SHA-256 hashes
  • Excluded Content: Documentation of skipped files and folders
  • Build Statistics: Total file counts and processing summary
  • Manifest Integration: Links to generated manifest files (if applicable)

Enterprise Integration

Audit reports support:

  • Compliance Documentation: Complete file inventory and processing records
  • Change Management: Detailed tracking of included and excluded content
  • Security Monitoring: File-level hash tracking and integrity validation
  • Process Documentation: Reproducible build evidence for governance

For comprehensive audit reporting information, see the Audit Reporting guide.

Use Cases

  • Pre-publishing validation: Review package structure before uploading to IPMHub
  • Content verification: Ensure only necessary files are included in your package
  • Structure testing: Validate directory and file organization
  • Documentation review: Check if READMEs and other documentation files are properly included
  • Dry run testing: Preview which files will be included without performing actual file operations
  • Enterprise Compliance: Generate verified packages with audit trails for governance requirements
  • Security Assurance: Create cryptographically verified packages for secure deployments

Build Process

When you run the ipm build command, IPM performs the following steps:

  1. Source scanning: Analyzes the source directory structure
  2. Content preparation: Organizes files according to IPMHub package standards
  3. Target creation: Creates the target directory if it doesn’t exist (unless using --dry-run)
  4. Content copying: Copies prepared content to the target directory (unless using --dry-run)
  5. Manifest generation: Creates cryptographic manifest if --include-manifest is specified
  6. Audit documentation: Generates summary report if --summary-file is specified

When using the --dry-run parameter, the command will output what would happen without making any actual changes to your filesystem. This is especially useful for verifying your package’s content before building or publishing.

Enhanced Build Intelligence

IPM 0.10.0 includes improved build system intelligence with expanded file and folder exclusions:

Automatic File Exclusions

The build system automatically excludes these file types:

  • .userosscache, .DS_Store, .Thumbs.db - System cache and thumbnail files
  • .log, .pyc, .pyo - Logging and Python bytecode files
  • .ps1xml, .psc1 - PowerShell configuration files
  • .class, .o, .obj - Compiled object files
  • .dll, .exe, .so, .dylib - Binary executables and libraries
  • .iso, .trace, .pid - System and debugging artifacts

Intelligent Folder Exclusions

Enhanced folder exclusion logic automatically removes:

  • bin - Binary output directories
  • __pycache__ - Python cache directories
  • .egg, .egg-info, .whl - Python package metadata

Default Behavior

  • Empty Folder Handling: Empty directories are no longer included by default
  • Workspace Exclusion: Improved workspace folder exclusion during build
  • Consistency: Resolved edge cases where excluded items were incorrectly included

Dry Run Output

When executing with --dry-run, you’ll see output similar to:

Dry run mode - Package will not be built

Files to be included:
./main.tf
./variables.tf
./outputs.tf
./README.md
./examples/basic/main.tf
./modules/submodule/main.tf

Total: 6 files would be copied to ./dist

This allows you to review exactly what would be included in your build without affecting your filesystem.

After Building

After building your package, you can:

  1. Inspect the contents: Review the files and structure in the target directory
  2. Verify manifest: Check generated manifest file for verified packages
  3. Review audit report: Analyze build report for compliance documentation
  4. Make adjustments: Return to your source and make changes if needed
  5. Rebuild: Run the build command again to see your changes
  6. Publish: When satisfied, use ipm publish to upload your package

Integration with Other Commands

The ipm build command pairs well with:

  • ipm publish: To publish your verified package with automatic integrity verification
  • ipm add: To test your package by adding it to a test workspace after building
  • ipm export: To quickly download packages for comparison

Best Practices

  • Use --dry-run first to preview what files will be included
  • Keep your source directory clean and organized
  • Include a README.md file with comprehensive documentation
  • Use .gitignore or similar mechanisms to exclude unnecessary files
  • Run a build before every publish to verify package contents
  • Compare builds when making significant changes to ensure consistency
  • Use --include-manifest for enterprise deployments requiring verified packages
  • Generate audit reports with --summary-file for compliance requirements
  • Store build artifacts securely when using verified packages

Enterprise Workflow

For enterprise environments, combine verified packages with audit reporting:

# Create verified package with full audit trail
ipm build --source ./src --destination ./dist --include-manifest --summary-file ./audit/build-$(date +%Y%m%d-%H%M%S).json

This provides both cryptographic verification and complete compliance documentation for enterprise governance requirements.