WIP

The Move tool is a Diem wrapper that needs some TLC.... Bounties are available through the Tool Scrubbers Guild if you would like to contribute!

Move

The Move CLI is a vendor package and original documentation can be found here

Description

The Move command-line interface (Move CLI) is a tool that provides an easy way to interact with Move, to experiment with writing and running Move code, and to experiment with developing new tools useful for Move development. To reflect this, the Move CLI commands are grouped into three main subcommands:

package commands: are commands to create, compile, and test Move packages, as well as perform other operations related to packages. These do not rely on a Move Adapter implementation nor an implementation of storage.
sandbox commands: are commands that allow you to write Move modules and scripts, write and run scripts and tests, and view the resulting state of execution in a local sandboxed environment.
experimental commands: are experimental commands that are currently in development.

Every Move CLI command, with the exception of package create, is expected to be run within the context of a Move package.

Compliling

The libra CLI can be used to compile a Move package locally. The below example uses the HelloBlockchain in fixtures.

note

You will first need to uncomment [addresses] in Move.toml and add your address you will be using

[package]
name = 'test_publish'
version = '1.0.0'

#[addresses]
#this_address='0xd1281de242839fc939745996882c5fc2'

[dependencies.DiemFramework]
git = 'https://github.com/0LNetworkCommunity/diem.git'
rev = 'release'
subdir = 'diem-move/framework/diem-framework'

$ libra move compile --package-dir /libra-framework/tools/txs/tests/fixtures/test_publish

The above command will generate the below terminal output:

Compiling, may take a little while to download git dependencies...
UPDATING GIT DEPENDENCY https://github.com/0LNetworkCommunity/diem.git
INCLUDING DEPENDENCY DiemFramework
INCLUDING DEPENDENCY DiemStdlib
INCLUDING DEPENDENCY MoveStdlib
BUILDING test_publish

Compiling and unit testing Move

The libra CLI can also be used to compile and run unit tests locally. In this example, we'll use the HelloBlockchain in fixtures.

$ libra move test --package-dir /libra-framework/tools/txs/tests/fixtures/test_publish

The above command will generate the following terminal output:

INCLUDING DEPENDENCY DiemFramework
INCLUDING DEPENDENCY DiemStdlib
INCLUDING DEPENDENCY MoveStdlib
BUILDING test_publish
Running Move unit tests
Test result: OK. Total tests: 0; passed: 0; failed: 0

Generating test coverage details for Move

The libra CLI can be used to analyze and improve the testing of your Move modules. To use this feature:

In your libra source checkout, navigate to the libra-framework/framework/move-stdlib directory.
Execute the command:
```
$ libra move test --coverage
```
Receive results in standard output containing the result for each test case followed by a basic coverage summary resembling:
```
BUILDING MoveStdlib
```

Running Move unit tests [ PASS ] 0x1::vector_tests::append_empties_is_empty [ PASS ] 0x1::option_tests::borrow_mut_none [ PASS ] 0x1::fixed_point32_tests::ceil_can_round_up_correctly [ PASS ] 0x1::features::test_change_feature_txn [ PASS ] 0x1::bcs_tests::bcs_bool [ PASS ] 0x1::bit_vector_tests::empty_bitvector [ PASS ] 0x1::option_tests::borrow_mut_some Test result: OK. Total tests: 149; passed: 149; failed: 0 +-------------------------+ | Move Coverage Summary | +-------------------------+ Module 0000000000000000000000000000000000000000000000000000000000000001::bcs

% Module coverage: NaN Module 0000000000000000000000000000000000000000000000000000000000000001::fixed_point32 % Module coverage: 100.00 Module 0000000000000000000000000000000000000000000000000000000000000001::hash % Module coverage: NaN Module 0000000000000000000000000000000000000000000000000000000000000001::vector % Module coverage: 92.19 Module 0000000000000000000000000000000000000000000000000000000000000001::error % Module coverage: 0.00 Module 0000000000000000000000000000000000000000000000000000000000000001::acl % Module coverage: 0.00 Module 0000000000000000000000000000000000000000000000000000000000000001::bit_vector % Module coverage: 97.32 Module 0000000000000000000000000000000000000000000000000000000000000001::signer % Module coverage: 100.00 Module 0000000000000000000000000000000000000000000000000000000000000001::features % Module coverage: 69.41 Module 0000000000000000000000000000000000000000000000000000000000000001::option % Module coverage: 100.00 Module 0000000000000000000000000000000000000000000000000000000000000001::string % Module coverage: 81.82 +-------------------------+ | % Move Coverage: 83.50 | +-------------------------+ Please use libra move coverage -h for more detailed test coverage of this package

4. Optionally, narrow down your test runs and results to a specific package name with the `--filter` option, like so:
```bash
$ libra move test --coverage --filter vector

With results like:

BUILDING MoveStdlib
Running Move unit tests
[ PASS    ] 0x1::bit_vector_tests::empty_bitvector
[ PASS    ] 0x1::vector_tests::append_empties_is_empty
[ PASS    ] 0x1::bit_vector_tests::index_bit_out_of_bounds
[ PASS    ] 0x1::vector_tests::append_respects_order_empty_lhs

Find failures and iteratively improve your testing and running these commands to eliminate gaps in your testing coverage.

Proving Move

note

This functionality is currently unavailable... Check back soon

Profiling gas usage

note

This functionality is currently unavailable... Check back soon

Debugging and printing stack trace

In this example, we will use DebugDemo in debug-move-example.

Now, you can use debug::print and debug::print_stack_trace in your DebugDemo Move file.

NOTE: This command does not work but gives an example for coding best practices

$ libra move test --package-dir https://github.com/aptos-labs/aptos-core/tree/main/crates/aptos/debug-move-example

The command will generate the following output:

Running Move unit tests
[debug] 0000000000000000000000000000000000000000000000000000000000000001
Call Stack:
    [0] 0000000000000000000000000000000000000000000000000000000000000001::Message::sender_can_set_message

        Code:
            [4] CallGeneric(0)
            [5] MoveLoc(0)
            [6] LdConst(0)
          > [7] Call(1)
            [8] Ret

        Locals:
            [0] -
            [1] 0000000000000000000000000000000000000000000000000000000000000001


Operand Stack:

Publishing a Move package with a named address

note

Named Addresses is currently unavailable... Check back soon

tip

As an open source project, the source code as well as compiled code published to the 0L Network is inherently open by default. This means code you upload may be downloaded from on-chain data. Even without source access, it is possible to regenerate Move source from Move bytecode. To disable source access, publish with the --included-artifacts none argument, like so:

libra move publish --included-artifacts none

tip

When publishing Move modules, if multiple modules are in one package, then all the modules in this package must have the same account. If they have different accounts, then the publishing will fail at the transaction level.

Running a Move function

note

The move run feature is currently not available but we have a work around for interacting with move functions. View a full description here

$ libra txs generate-transaction --function-id 0xd1281de242839fc939745996882c5fc2::message::set_message --args '42'

Deploying a package

note

The libra move publish feature is currently not available but we have a work around for interacting with move functions. View a full description here

$ libra txs publish --package-dir /libra-framework/tools/txs/tests/fixtures/test_publish

View functions

note

The libra move view feature is currently not available but we have a couple of work arounds for viewing move functions and values. View a full description here

$ libra query move-value --account 0xd1281de242839fc939745996882c5fc2 --module-name message --struct-name MessageHolder --key-name message

$ libra query view --function-id 0x1::reconfiguration::get_current_epoch

Move

Description​

Compliling​

Compiling and unit testing Move​

Generating test coverage details for Move​

Proving Move​

Profiling gas usage​

Debugging and printing stack trace​

Publishing a Move package with a named address​

Running a Move function​

Deploying a package​

View functions​

Description

Compliling

Compiling and unit testing Move

Generating test coverage details for Move

Proving Move

Profiling gas usage

Debugging and printing stack trace

Publishing a Move package with a named address

Running a Move function

Deploying a package

View functions