How to Use the Command 'sui move' (with Examples)

The sui move command is a tool designed for working with Move programming language source code. Move is a language initially developed for the Libra blockchain and has since become more widely adopted for its strong safety and resource management features. The sui move command facilitates various tasks, including creating new projects, building and testing projects, generating code coverage reports, and migrating projects to newer versions of the Move language. Below are several use cases that demonstrate the capabilities of the sui move command.

Use case 1: Create a New Move Project

Code:

sui move new project_name

Motivation:

When starting a new Move-based project, you need to initialize a project directory with all the necessary files and configurations. This command provides a boilerplate structure to kickstart your development process, allowing you to focus more on developing the core logic of your project rather than on setting up configurations.

Explanation:

• sui move: The base command that indicates we’re working with the Move language.
• new: Sub-command to create a new project.
• project_name: The name of the new project folder that will be created. For instance, if you plan to call your project “HelloMove,” you would replace project_name with “HelloMove.”

Example Output:

Created a new Move project in 'project_name' with the following structure:

project_name/
  ├── Move.toml
  ├── sources/
  └── tests/

Use case 2: Test the Move Project in the Current Directory

Code:

sui move test

Motivation:

Testing is a crucial part of development that ensures your code functions as expected. This command runs all tests defined in the current Move project, helping you catch errors or logical flaws before deploying your code further.

Explanation:

• sui move: Indicates working with Move source code.
• test: Sub-command to run tests in the current directory.

Example Output:

Running Move tests...
All tests passed successfully.

Use case 3: Test with Coverage and Get a Summary

Code:

sui move test --coverage; sui move coverage summary

Motivation:

Understanding the extent to which your tests cover your code’s execution paths is vital to gauging test effectiveness. This combination of commands runs your tests with coverage tracking enabled and then summarizes the coverage results, helping you identify untested areas.

Explanation:

• sui move test --coverage: Runs the tests with code coverage metrics enabled.
• ;: Command separator allowing execution of the next command.
• sui move coverage summary: Provides a summary of the code covered by the tests.

Example Output:

Running Move tests with coverage...
All tests passed successfully.
Coverage summary:
  - FileA.move: 75% covered
  - FileB.move: 90% covered

Use case 4: Find Which Parts of Your Code are Covered from Tests

Code:

sui move coverage source --module module_name

Motivation:

After generating a coverage report, it’s often useful to dive deeper into specific modules to see which parts were well-tested and which were not. This command provides granular insights into the coverage at the module level.

Explanation:

• sui move: Base command for working with Move projects.
• coverage: Sub-command for coverage-related tasks.
• source: Specifies that we want a detailed view of the source code coverage.
• --module: Flag indicating which module’s coverage details we want to examine.
• module_name: The name of the specific module you want to research. Replace module_name with the actual module name in your project.

Example Output:

Coverage for module 'module_name':
  - FunctionA: 80%
  - FunctionB: 60%
  - FunctionC: 100%

Use case 5: Build the Move Project in the Current Directory

Code:

sui move build

Motivation:

Building a project compiles the source code into bytecode that can be deployed and executed on a blockchain. This process is essential to verify that the source code is syntactically and semantically correct.

Explanation:

• sui move: Tool to interact with Move source code.
• build: Sub-command that compiles the Move source code into deployable bytecode.

Example Output:

Building Move project...
Build succeeded with 0 warnings and 0 errors.

Use case 6: Build the Move Project from the Given Path

Code:

sui move build --path path

Motivation:

Sometimes, you may want to build a project located in a different directory than your current working directory. This command facilitates compiling the Move project from any specified path.

Explanation:

• sui move: Command for handling Move projects.
• build: Sub-command to compile Move code.
• --path: Specifies the directory of the project you want to build.
• path: The path to the directory containing the Move project to be built.

Example Output:

Building Move project at 'path'...
Build succeeded with 0 warnings and 0 errors.

Use case 7: Migrate to Move 2024 for the Package at the Provided Path

Code:

sui move migrate path

Motivation:

As new versions of Move are released, they often come with optimizations, new features, and deprecations. This command aids you in updating an existing Move project to comply with the latest language specifications.

Explanation:

• sui move: Base command for interacting with Move projects.
• migrate: Sub-command indicating the action of version migration.
• path: The directory path of the Move package you want to migrate to the 2024 version.

Example Output:

Migrating project at 'path' to Move 2024...
Migration completed successfully.

Conclusion:

The sui move command is a powerful tool for managing Move language projects. From creating initial project structures, through building and testing, to upgrading to newer language versions, this command streamlines various aspects of Move development, allowing developers to focus on the innovation and logic central to their applications.