Dependencies

Protostar uses git submodules to manage dependencies in your project. In order to manage dependencies with Protostar, you must have git installed on your system and have the git executable added to the PATH environment variable. The PATH variable is a list of directories that your system searches for executables.

note

As a temporary solution, Protostar is using git submodules to manage dependencies. We recommend migrating your dependency management to Scarb.

Adding a dependency

To add a dependency to your Protostar project, run the following command from the project directory:

protostar install EXTERNAL_DEPENDENCY_REFERENCE

For example:

protostar install OpenZeppelin/[email protected]

danger

It is strongly discouraged to install the dependencies directly from the main branch, because the branch might be in unreleasable state. It is recommended to always include a tag in the External Dependency Reference format.

After running the install command, the dependency will be added by default to the lib directory in your project:

.
├── lib
│   └── cairo_contracts
│      └── src
├── protostar.toml
├── src
│   └── main.cairo
└── tests
    └── test_main.cairo

danger

Protostar will create a git commit after installing a dependency.

If you use a dependency that uses absolute imports, you will need to specify a cairo-path to the root directory of that dependency in your project. It is recommended to specify the cairo-path in the configuration file, as this setting can be reused by the build-cairo0 and test-cairo0 commands.

For example:

protostar.toml

[project]
protostar-version = "X.Y.Z"
cairo-path = ["lib/cairo-contracts/src"]

External dependency reference formats

Protostar supports the following ways of referencing external dependency:

Format	Example
GITHUB_ACCOUNT_NAME/REPO_NAME[@TAG]	OpenZeppelin/[email protected]
URL_TO_THE_REPOSITORY	https://github.com/OpenZeppelin/cairo-contracts
SSH_URI	[email protected]:OpenZeppelin/cairo-contracts.git

Aliases

Protostar allows you to install dependencies under a different name, in case of a name conflict between two GitHub users using the same library name. To install a package under a custom name, use name argument:

protostar install EXTERNAL_DEPENDENCY_REFERENCE --name CUSTOM_NAME

For example:

protostar install OpenZeppelin/[email protected] --name open_zeppelin

Installing dependencies after cloning a repository

If you git clone a Protostar project with dependencies without using the --recurse-submodules flag, you will need to install the dependencies using Protostar. Otherwise, your project will not compile and tests will fail. To do this, run protostar install in the project directory.

protostar install

Updating dependencies

If the default branch of a dependency's repository uses tags, Protostar will update the dependency by pulling a commit marked with the newest tag. If the repository does not use tags, Protostar will pull the most recent commit from the default branch.

To update a single dependency, run:

protostar update LOCAL_DEPENDENCY_REFERENCE/EXTERNAL_DEPENDENCY_REFERENCE

LOCAL_DEPENDENCY_REFERENCE is a directory name of a dependency.

To update all dependencies, run:

protostar update

Removing dependencies

To remove a dependency from your Protostar project, use the protostar remove command and specify the LOCAL_DEPENDENCY_REFERENCE or EXTERNAL_DEPENDENCY_REFERENCE of the dependency.

protostar remove LOCAL_DEPENDENCY_REFERENCE/EXTERNAL_DEPENDENCY_REFERENCE

For example, to remove the cairo_contracts dependency, run:

protostar remove `cairo_contracts`

This command will remove the dependency and all its associated files from your project. Protostar will also create a git commit due to reliance on git submodules.