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]

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

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

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

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)

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.

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. Make adjustments: Return to your source and make changes if needed
  3. Rebuild: Run the build command again to see your changes
  4. 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
  • 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