Packages

Packages allow Move programmers to more easily re-use code and share it across projects. The Move package system allows programmers to easily:

  • Define a package containing Move code;
  • Parameterize a package by named addresses;
  • Import and use packages in other Move code and instantiate named addresses;
  • Build packages and generate associated compilation artifacts from packages; and
  • Work with a common interface around compiled Move artifacts.

Package Layout and Manifest Syntax

A Move package source directory contains a Move.toml package manifest file, a generated Move.lock file, and a set of subdirectories:

a_move_package
├── Move.toml      (required)
├── Move.lock      (generated)
├── sources        (required)
├── doc_templates  (optional)
├── examples       (optional, test & dev mode)
└── tests          (optional, test mode)

The directories and files labeled "required" must be present for a directory to be considered a Move package and built. Optional directories may be present, and if so, they will be included in the compilation process depending on the mode used to build the package. For instance, when built in "dev" or "test" modes, the tests and examples directories will also be included.

Going through each of these in turn:

  1. The Move.toml file is the package manifest and is required for a directory to be considered a Move package. This file contains metadata about the package, such as name, dependencies, and so on.
  2. The Move.lock file is generated by the Move CLI and contains the fixed build versions of the package and its dependencies. It is used to ensure consistent versions are used across different builds and that changes in dependencies are apparent as a change in this file.
  3. The sources directory is required and contains the Move modules that make up the package. Modules in this directory will always be included in the compilation process.
  4. The doc_templates directory can contain documentation templates that will be used when generating documentation for the package.
  5. The examples directory can hold additional code to be used only for development and/or tutorials, this will not be included when compiled outside of test or dev modes.
  6. The tests directory can contain Move modules that are only included when compiled in test mode or when Move unit tests are run.

Move.toml

The Move package manifest is defined within the Move.toml file and has the following syntax. Optional fields are marked with *, + denotes one or more elements:

[package]
name = <string>
edition* = <string>      # e.g., "2024.alpha" to use the Move 2024 edition,
                         # currently in alpha. Will default to the latest stable edition if not specified.
license* = <string>              # e.g., "MIT", "GPL", "Apache 2.0"
authors* = [<string>,+]  # e.g., ["Joe Smith (joesmith@noemail.com)", "John Snow (johnsnow@noemail.com)"]

# Additional fields may be added to this section by external tools. E.g., on Sui the following sections are added:
published-at* = "<hex-address>" # The address that the package is published at. Should be set after the first publication.

[dependencies] # (Optional section) Paths to dependencies
# One or more lines declaring dependencies in the following format

# ##### Local Dependencies #####
# For local dependencies use `local = path`. Path is relative to the package root
# Local = { local = "../path/to" }
# To resolve a version conflict and force a specific version for dependency
# override you can use `override = true`
# Override = { local = "../conflicting/version", override = true }
# To instantiate address values in a dependency, use `addr_subst`
<string> = {
    local = <string>,
    override* = <bool>,
    addr_subst* = { (<string> = (<string> | "<hex_address>"))+ }
}

# ##### Git Dependencies #####
# For remote import, use the `{ git = "...", subdir = "...", rev = "..." }`.
# Revision must be supplied, it can be a branch, a tag, or a commit hash.
# If no `subdir` is specified, the root of the repository is used.
# MyRemotePackage = { git = "https://some.remote/host.git", subdir = "remote/path", rev = "main" }
<string> = {
    git = <URL ending in .git>,
    subdir=<path to dir containing Move.toml inside git repo>,
    rev=<git commit hash>,
    override* = <bool>,
    addr_subst* = { (<string> = (<string> | "<hex_address>"))+ }
}

[addresses]  # (Optional section) Declares named addresses in this package
# One or more lines declaring named addresses in the following format
# Addresses that match the name of the package must be set to `"0x0"` or they will be unable to be published.
<addr_name> = "_" | "<hex_address>" # e.g., std = "_" or my_addr = "0xC0FFEECAFE"

# Named addresses will be accessible in Move as `@name`. They're also exported:
# for example, `std = "0x1"` is exported by the Standard Library.
# alice = "0xA11CE"

[dev-dependencies] # (Optional section) Same as [dependencies] section, but only included in "dev" and "test" modes
# The dev-dependencies section allows overriding dependencies for `--test` and
# `--dev` modes. You can e.g., introduce test-only dependencies here.
# Local = { local = "../path/to/dev-build" }
<string> = {
    local = <string>,
    override* = <bool>,
    addr_subst* = { (<string> = (<string> | "<hex_address>"))+ }
}
<string> = {
    git = <URL ending in .git>,
    subdir=<path to dir containing Move.toml inside git repo>,
    rev=<git commit hash>,
    override* = <bool>,
    addr_subst* = { (<string> = (<string> | "<hex_address>"))+ }
}

[dev-addresses] # (Optional section) Same as [addresses] section, but only included in "dev" and "test" modes
# The dev-addresses section allows overwriting named addresses for the `--test`
# and `--dev` modes.
<addr_name> = "<hex_address>" # e.g., alice = "0xB0B"

An example of a minimal package manifest:

[package]
name = "AName"

An example of a more standard package manifest that also includes the Move standard library and instantiates the named address std from the LocalDep package with the address value 0x1:

[package]
name = "AName"
license = "Apache 2.0"

[addresses]
address_to_be_filled_in = "_"
specified_address = "0xB0B"

[dependencies]
# Local dependency
LocalDep = { local = "projects/move-awesomeness", addr_subst = { "std" = "0x1" } }
# Git dependency
MoveStdlib = { git = "https://github.com/MystenLabs/sui.git", subdir = "crates/sui-framework/packages/move-stdlib", rev = "framework/mainnet" }

[dev-addresses] # For use when developing this module
address_to_be_filled_in = "0x101010101"

Most of the sections in the package manifest are self explanatory, but named addresses can be a bit difficult to understand so we examine them in more detail in Named Addresses During Compilation.

Named Addresses During Compilation

Recall that Move has named addresses and that named addresses cannot be declared in Move. Instead they are declared at the package level: in the manifest file (Move.toml) for a Move package you declare named addresses in the package, instantiate other named addresses, and rename named addresses from other packages within the Move package system.

Let's go through each of these actions, and how they are performed in the package's manifest one-by-one:

Declaring Named Addresses

Let's say we have a Move module in example_pkg/sources/A.move as follows:

module named_addr::a {
    public fun x(): address { @named_addr }
}

We could in example_pkg/Move.toml declare the named address named_addr in two different ways. The first:

[package]
name = "example_pkg"
...
[addresses]
named_addr = "_"

Declares named_addr as a named address in the package example_pkg and that this address can be any valid address value. In particular, an importing package can pick the value of the named address named_addr to be any address it wishes. Intuitively you can think of this as parameterizing the package example_pkg by the named address named_addr, and the package can then be instantiated later on by an importing package.

named_addr can also be declared as:

[package]
name = "example_pkg"
...
[addresses]
named_addr = "0xCAFE"

which states that the named address named_addr is exactly 0xCAFE and cannot be changed. This is useful so other importing packages can use this named address without needing to worry about the exact value assigned to it.

With these two different declaration methods, there are two ways that information about named addresses can flow in the package graph:

  • The former ("unassigned named addresses") allows named address values to flow from the importation site to the declaration site.
  • The latter ("assigned named addresses") allows named address values to flow from the declaration site upwards in the package graph to usage sites.

With these two methods for flowing named address information throughout the package graph the rules around scoping and renaming become important to understand.

Scope and Renaming of Named Addresses

A named address N in a package P is in scope if:

  1. P declares a named address N; or
  2. A package in one of P's transitive dependencies declares the named address N and there is a dependency path in the package graph between between P and the declaring package of N with no renaming of N.

Additionally, every named address in a package is exported. Because of this and the above scoping rules each package can be viewed as coming with a set of named addresses that will be brought into scope when the package is imported, e.g., if you import example_pkg, that import will also bring the named_addr named address into scope. Because of this, if P imports two packages P1 and P2 both of which declare a named address N an issue arises in P: which "N" is meant when N is referred to in P? The one from P1 or P2? To prevent this ambiguity around which package a named address is coming from, we enforce that the sets of scopes introduced by all dependencies in a package are disjoint, and provide a way to rename named addresses when the package that brings them into scope is imported.

Renaming a named address when importing can be done as follows in our P, P1, and P2 example above:

[package]
name = "P"
...
[dependencies]
P1 = { local = "some_path_to_P1", addr_subst = { "P1N" = "N" } }
P2 = { local = "some_path_to_P2"  }

With this renaming N refers to the N from P2 and P1N will refer to N coming from P1:

module N::A {
    public fun x(): address { @P1N }
}

It is important to note that renaming is not local: once a named address N has been renamed to N2 in a package P all packages that import P will not see N but only N2 unless N is reintroduced from outside of P. This is why rule (2) in the scoping rules at the start of this section specifies a "dependency path in the package graph between between P and the declaring package of N with no renaming of N."

Instantiating Named Addresses

Named addresses can be instantiated multiple times across the package graph as long as it is always with the same value. It is an error if the same named address (regardless of renaming) is instantiated with differing values across the package graph.

A Move package can only be compiled if all named addresses resolve to a value. This presents issues if the package wishes to expose an uninstantiated named address. This is what the [dev-addresses] section solves in part. This section can set values for named addresses, but cannot introduce any named addresses. Additionally, only the [dev-addresses] in the root package are included in dev mode. For example a root package with the following manifest would not compile outside of dev mode since named_addr would be uninstantiated:

[package]
name = "example_pkg"
...
[addresses]
named_addr = "_"

[dev-addresses]
named_addr = "0xC0FFEE"

Usage and Artifacts

The Move package system comes with a command line option as part of the CLI: sui move <command> <command_flags>. Unless a particular path is provided, all package commands will run in the current enclosing Move package. The full list of commands and flags for the Move CLI can be found by running sui move --help.

Artifacts

A package can be compiled using CLI commands. This will create a build directory containing build-related artifacts (including bytecode binaries, source maps, and documentation). The general layout of the build directory is as follows:

a_move_package
├── BuildInfo.yaml
├── bytecode_modules
│   ├── dependencies
│   │   ├── <dep_pkg_name>
│   │   │   └── *.mv
│   │   ...
│   │   └──  <dep_pkg_name>
│   │       └── *.mv
│   ...
│   └── *.mv
├── docs
│   ├── dependencies
│   │   ├── <dep_pkg_name>
│   │   │   └── *.md
│   │   ...
│   │   └──  <dep_pkg_name>
│   │       └── *.md
│   ...
│   └── *.md
├── source_maps
│   ├── dependencies
│   │   ├── <dep_pkg_name>
│   │   │   └── *.mvsm
│   │   ...
│   │   └──  <dep_pkg_name>
│   │       └── *.mvsm
│   ...
│   └── *.mvsm
└── sources
    ...
    └── *.move
    ├── dependencies
    │   ├── <dep_pkg_name>
    │   │   └── *.move
    │   ...
    │   └──  <dep_pkg_name>
    │       └── *.move
    ...
    └── *.move

Move.lock

The Move.lock file is generated at the root of the Move package when the package is built. The Move.lock file contains information about your package and its build configuration, and acts as a communication layer between the Move compiler and other tools, like chain-specific command line interfaces and third-party package managers.

Like the Move.toml file, the Move.lock file is a text-based TOML file. Unlike the package manifest however, the Move.lock file is not intended for you to edit directly. Processes on the toolchain, like the Move compiler, access and edit the file to read and append relevant information to it. You also must not move the file from the root, as it needs to be at the same level as the Move.toml manifest in the package.

If you are using source control for your package, it's recommended practice to check in the Move.lock file that corresponds with your desired built or published package. This ensures that every build of your package is an exact replica of the original, and that changes to the build will be apparent as changes to the Move.lock file.

The Move.lock file is a TOML file that currently contains the following fields.

Note: other fields may be added to the lock file either in the future, or by third-party package package managers as well.

The [move] Section

This section contains the core information needed in the lockfile:

  • The version of the lockfile (needed for backwards compatibility checking, and versioning lockfile changes in the future).
  • The hash of the Move.toml file that was used to generate this lock file.
  • The hash of the Move.lock file of all dependencies. If no dependencies are present, this will be an empty string.
  • The list of dependencies.
[move]
version = <string> # Lock file version, used for backwards compatibility checking.
manifest_digest = <hash> # Sha3-256 hash of the Move.toml file that was used to generate this lock file.
deps_digest = <hash> # Sha3-256 hash of the Move.lock file of all dependencies. If no dependencies are present, this will be an empty string.
dependencies = { (name = <string>)* } # List of dependencies. Not present if there are no dependencies.

The [move.package] Sections

After the Move compiler resolves each of the dependencies for the package it writes the location of the dependency to the Move.lock file. If a dependency failed to resolve, the compiler will not write the Move.lock file and the build fails. If all dependencies resolve, the Move.lock file contains the locations (local and remote) of all of the package's transitive dependencies. These will be stored in the Move.lock file in the following format:

# ...

[[move.package]]
name = "A"
source = { git = "https://github.com/b/c.git", subdir = "e/f", rev = "a1b2c3" }

[[move.package]]
name = "B"
source = { local = "../local-dep" }

The [move.toolchain-version] Section

As mentioned above, additional fields may be added to the lock file by external tools. For example, the Sui package manager adds toolchain version information to the lock file that can then be used for on-chain source verification:

# ...

[move.toolchain-version]
compiler-version = <string> # The version of the Move compiler used to build the package, e.g. "1.21.0"
edition = <string> # The edition of the Move language used to build the package, e.g. "2024.alpha"
flavor = <string> # The flavor of the Move compiler used to build the package, e.g. "sui"