How to Use the Command 'pio package' (with Examples)

The pio package command is a versatile tool for managing packages in the PlatformIO ecosystem. It allows developers to create, publish, and manage packages with relative ease. This command is crucial for developers who maintain libraries or tools in the PlatformIO Registry. One of the key features is the flexibility in managing the lifecycle of a package, including creating packages, publishing them, restricting access, and even undoing removals if necessary. The command provides fine-grained control over when and how packages are released to the public or restricted audiences, ensuring that developers can manage their packages with precision.

Use Case 1: Create a package tarball from the current directory

Code:

pio package pack --output path/to/package.tar.gz

Motivation:
Creating a package tarball is essential for developers who wish to share their package in a pre-packaged format while still retaining local control. This operation is ideal when testing the package locally before publishing it or sharing it offline.

Explanation:

• pio package pack: This part of the command tells PlatformIO to initiate the packaging process.
• --output path/to/package.tar.gz: This specifies the destination path and file name for the tarball. The --output argument is necessary to designate where the packaged file should be stored.

Example Output:
After running this command, you’ll end up with a tarball at the specified location, which contains all necessary files from the current directory packaged within it.

Use Case 2: Create and publish a package tarball from the current directory

Code:

pio package publish

Motivation:
Publishing a package directly from the current directory simplifies the process of making your package available to others. This is particularly useful for developers who are confident in their package’s state and are ready to share their work with the community.

Explanation:

• pio package publish: This command directly publishes the package that exists in the current directory to the PlatformIO Registry.

Example Output:
Successful execution will result in the package being available in the PlatformIO Registry for others to access.

Use Case 3: Publish the current directory and restrict public access to it

Code:

pio package publish --private

Motivation:
Sometimes, developers need to share their package with a select group rather than the general public. This command allows for such controlled distribution, ensuring privacy and restricting access.

Explanation:

• pio package publish: The base command for publishing the package.
• --private: An argument that ensures the package is published but not publicly accessible, restricting it to authorized users only.

Example Output:
The package will be published with restricted access, and it will not appear in general searches, adhering to privacy requirements.

Use Case 4: Publish a package

Code:

pio package publish path/to/package.tar.gz

Motivation:
This command allows developers to publish a pre-prepared package tarball, which could have been prepared offline or on another machine, ensuring ease and flexibility in the publishing process.

Explanation:

• pio package publish: Initiates the publishing process.
• path/to/package.tar.gz: Points to the location of the tarball that needs to be published.

Example Output:
Once successful, the specified tarball is published to the PlatformIO Registry, making it accessible to other users.

Use Case 5: Publish a package with a custom release date (UTC)

Code:

pio package publish path/to/package.tar.gz --released-at "2021-04-08 21:15:38"

Motivation:
Setting a custom release date can be vital for organizations or developers who need to time releases with product launches or marketing campaigns, thus aligning the package release with other business activities.

Explanation:

• pio package publish: The base command for kicking off the publishing process.
• path/to/package.tar.gz: The tarball location that is being published.
• --released-at "2021-04-08 21:15:38": This argument specifies the exact datetime, in UTC, when the package should be considered released.

Example Output:
The package is published with a release date that is different from the publishing date, reflecting in its metadata within the Registry.

Use Case 6: Remove all versions of a published package from the registry

Code:

pio package unpublish package

Motivation:
Unpublishing all versions of a package is critical when a security vulnerability or major error is discovered, necessitating complete withdrawal to protect users from faulty code.

Explanation:

• pio package unpublish: Begins the unpublishing process.
• package: The name of the package to be removed.

Example Output:
All versions of the specified package are removed from the registry, making them unavailable for download.

Use Case 7: Remove a specific version of a published package from the registry

Code:

pio package unpublish package@version

Motivation:
When only one particular version of a package is found problematic, it’s possible to unpublish just that version, preserving the credibility and usability of other versions.

Explanation:

• pio package unpublish: Initiates the removal.
• package@version: Specifies the exact package version to remove from the registry.

Example Output:
The specified version of the package is removed, while other versions remain unaffected.

Use Case 8: Undo the removal, putting all versions or a specific version of the package back into the registry

Code:

pio package unpublish --undo package@version

Motivation:
If a package version was removed by mistake or the underlying issue was resolved quickly, this command helps restore the package, maintaining user access and continuity of use.

Explanation:

• pio package unpublish: Initiates the command, here with a different intention.
• --undo: Signals the operation to reverse a previous unpublish action.
• package@version: Specifies which package version to restore.

Example Output:
Previously unpublished versions are reinstated in the registry, retaining their original listing status.

Conclusion:

The pio package command offers a comprehensive suite of options for developers to manage their packages with precision in the PlatformIO ecosystem. These examples illustrate its utility and flexibility in different scenarios, enabling effective package lifecycle management.