Packaging Quickstart

Introduction

Populus can be used as a package manager to interact with any ERC190 smart contract packages.

Project Manifest

In order to take advantage of the packaging features you will first need to create a package manifest for your project. This can either be done manually or using the command line helper $ populus package init which will present an interactive prompt for creating the ethpm.json file.

$ populus package init
Writing new ethpm.json file.
Package Name: fancy-greeter
Author(s) [[]]: Piper Merriam <pipermerriam@gmail.com>
Version [1.0.0]:
License [MIT]:
Description []: A fancy greeter contract
Keywords [[]]: greeter, greetings
Links [{}]:
Wrote package manifest: ethpm.json

Installing Packages

Packages can be installed using the $populus package install command. Packages may be specified in the following formats.

• populus package install .:

  To install all of the declared dependencies found within the project’s package manifest.

• populus package install some-package-name

  To install a named package some-package-name sourced from a package index.

• populus package install ipfs://QmUwVUMVtkVctrLDeL12SoeCPUacELBU8nAxRtHUzvtjND

  To install directly from a release lockfile via IPFS

• populus package install /path/to/release-lockfile.json

  To install directly from a release lockfile on the local filesystem.

Populus also supports installing packages under aliased names. This can be used to allow multiple versions of the same package to be installed in tandem.

• populus package install some-alias:some-package-name

  To install a named package some-package-name under the name some-alias sourced from a package index.

• populus package install some-alias@ipfs://QmUwVUMVtkVctrLDeL12SoeCPUacELBU8nAxRtHUzvtjND

  To install directly from a release lockfile via IPFS using the name some-alias.

• populus package install some-alias@/path/to/release-lockfile.json

  To install directly from a release lockfile on the local filesystem using the name some-alias

Packages are installed in the ./installed_packages directory in the root project directory under their aliased name, or their package name if no alias is used.

When a package is installed it is automatically saved to the project dependencies within the package manifest. This can be disabled by passing in the --no-save flag during installation.

Using Contracts from Installed Packages

Importing a contract from an installed package is done by prefixing the source path with the name of the installed package, or the alias name if an alias was used.

Lets use the common owned pattern for an example. Suppose we have the owned package installed in our project. We know that this package has a single solidity source file that contains the owned contract located at ./contracts/owned.sol.

To import a contract from this file into local solidity source files you would simply prefix the import path with the package name.

pragma solidity ^0.4.0;

import "owned/contracts/owned.sol";

contract MyContract is owned {
    ...
}

Note

If you install a package which either has source files which do not compile with the solidity compiler version you are using, or which have a pragma solidity statement which is incompatable with your version of solidity then compilation will fail.

Library Linking

If you have a package installed which contains a library contract with a deployed instance of that library, populus will automatically find and link against that existing deployed library. One of the default contract backends that populus uses will check all installed packages

Building and Publishing Releases

Populus can be used to build and publish packages to The Ethereum Package Registry or any registry which implements a compatable API.

To build a release use the $ populus package build command.