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.12.0 includes comprehensive build control with .ipmignore support and improved exclusion reporting:

.ipmignore Support

Create a .ipmignore file in your package root to customize exclusions using familiar gitignore syntax:

# Exclude temporary files
*.tmp
*.log

# Exclude development directories
dev/
testing/

# Include specific files that would normally be excluded
!important.exe
!.ipmignore

Default File Exclusions

The build system automatically excludes these file types:

  • .lnk, .gitignore, .hgignore, .svnignore, .suo, .user, .sln.docstates
  • .userosscache, .DS_Store, .Thumbs.db
  • .log, .pyc, .pyo, .psc1
  • .class, .o, .obj
  • .dll, .exe, .so, .dylib
  • .iso, .trace, .pid

Default Folder Exclusions

The build system automatically excludes these folders:

  • .git, .svn, .hg, .vscode, .idea, .terraform
  • node_modules, obj, bin
  • __pycache__, .egg, .egg-info, .whl

Special File Handling

Certain files are “ignored by default” but can be included via .ipmignore:

  • .ipmignore, .ps1xml, .bat
  • Special exclusions: .terraform.lock.hcl
  • Use !filename in .ipmignore to include these files

Package Size and Structure Limits

  • Total Package Size: Maximum 20MB
  • File Count: Maximum 1500 files per package
  • Directory Depth: Maximum 8 levels deep
  • Individual File Size: Maximum 1MB per file
  • Filename Length: Maximum 260 characters per filename
  • Package Name: Maximum 64 characters
  • Owner Name: Maximum 38 characters

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 and review exclusion reasons
  • Create a .ipmignore file to customize file exclusions for your specific needs
  • Keep your source directory clean and organized
  • Include a README.md file with comprehensive documentation
  • Respect package limits: maximum 1500 files, 20MB total, 8 directory levels deep, 1MB per file, 260 char filenames
  • 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.