{"owner":"aptos-labs","repo":"aptos-core","hasSkills":true,"totalSkillsCount":8,"totalTokensCount":8420,"categories":["plugin-manifest"],"hasMcp":false,"mcpConfig":null,"found":["third_party/move/extensions/README.md","third_party/move/tools/README.md","third_party/move/tools/move-package/README.md","third_party/move/extensions/move-table-extension/README.md","third_party/move/tools/move-cli/README.md","third_party/move/tools/move-unit-test/README.md","third_party/move/move-examples/diem-framework/move-packages/core/README.md","aptos-move/move-examples/large_packages/README.md"],"skills":{"third_party/move/extensions/README.md":"This tree contains extensions to the Move core language and runtime. Those extensions are not enabled by\ndefault but can be integrated into a Move-based environment following the instructions found for each individual\nextension.\n\nSome extensions may eventually become part of the core language after some period of stabilization.\n","third_party/move/tools/README.md":"---\nid: tools\ntitle: Move Tools\ncustom_edit_url: https://github.com/move-language/move/edit/main/language/tools/README.md\n---\n\n# Summary\n\nMove has a number of tools associated with it. This directory contains all,\nor almost all of them. The following crates in this directory are libraries\nthat are used by the [`move-cli`](./move-cli) `package` subcommand:\n\n* `move-bytecode-viewer`\n* `move-disassembler`\n* `move-explain`\n* `move-unit-test`\n* `move-package`\n* `move-coverage`\n\nIn this sense each of these crates defines the core logic for a specific\npackage command, e.g., how to run and report unit tests, or collect and\ndisplay test coverage information. However, the Move CLI is responsible for\nstitching these commands together, e.g., when running a move unit test the\nMove CLI is responsible for first making sure the package was built in\n`test` mode ( using the `move-package` library), collecting the test plan\nto feed to the `move-unit-test` library, and returning a non-zero error\ncode if a test fails.\n\nGenerally, if you want to see how various tools interact with each other,\nor how a normal Move user would interact with these tools, you should first\nlook at the Move CLI (specifically the `package` subdirectory/command) as\nthat is responsible for stitching everything together. If you are looking\nfor where the logic for a specific tool is defined, this is most likely in\nthe specific crate for that tool (e.g., if you want to see how TUIs are\nhandled for the `move-bytecode-viewer` that's defined in the\n`move-bytecode-viewer` crate, and not the `move-cli` crate).\n\nSome of the crates mentioned above are also binaries at the moment, however\nthey should all be able to be made libaries only, with the possible\nexception of the `move-coverage` crate. The primary reason for this, is\nthat this tool can collect and report test coverage statistics across\nmultiple packages, and multiple runs over a package. This functionality is\nimportant if you have a large functional test suite such as Diem's and want\nto gather coverage information across all of them.\n\nThe `move-resource-viewer`, and `read-write-set` similarly are library\ncrates that are used by and exposed by the Move CLI, but not through the\n`package` subcommand.\n\nThe `move-bytecode-utils` crates holds general\nutilities for working with Move bytecode, e.g., computing the dependency\norder for modules.\n","third_party/move/tools/move-package/README.md":"---\nid: move-package\ntitle: Move Package\ncustom_edit_url: https://github.com/move-language/move/edit/main/language/tools/move-package/README.md\n---\n\n# Summary\n\nThe Move package crate contains the logic for parsing, resolving, and\nbuilding Move packages. It is meant to be used as a library, both for\nbuilding packages (e.g., by the Move CLI), or by other applications that\nmay be working with Move packages. The package system is split into three\nmain phases: parsing, resolution, and compilation.\n\n## Parsing and Manifest Layout\n\nThe parsing and manifest layout logic is defined in the\n[`./src/source_package`](./src/source_package) directory. This defines the\nlayout and the set of required and optional directories for a Move package\nin [`./src/source_package/layout.rs`](./src/source_package/layout.rs), it\ndefines the format of the parsed Move package manifest (\"`Move.toml`\") in\n[`./src/source_package/parsed_manifest.rs`](./src/source_package/parsed_manifest.rs),\nand it defines the parser for the Move package manifest in\n[`./src/source_package/manifest_parser.rs`](./src/source_package/manifest_parser.rs).\nNote that we don't have a tokenizer/lexer as we use the TOML lexer. This\nalso resolves git dependencies to where they will live on the local file\nsystem (but does not clone them).\n\n## Resolution\n\nThe resolution phase is responsible for resolving all packages and building\nthe package graph which represents the dependency relations between\npackages. It is also responsible for ensuring that all named addresses have\na value assigned to them, and that there are no conflicting assignments.\nThe package graph is rooted at the package being built and is a DAG.\n\nWhen building the package graph we do the following conceptual operations:\nverify that dependencies exist at the declared locations, that their\npackage names and source digests match (if applicable), clone git\ndependencies if they don't already exist locally, build a dependency graph\nof Move packages and ensure this forms a DAG, compute an\nassignment for each named address in each Move package in the package\ngraph, and ensure that the resulting named address assignment is valid.\n\nAll of the above steps are fairly straightforward, with the possible\nexception of named addresses: each package will have a set of in-scope\nnamed addresses. The set of in-scope named addresses for a package `P` is\ndefined as the transitive closure of all named addresses in the\ndependencies of `P`. Additionally, a package can rename named addresses\nthat are in-scope as long as the final assignment of a value to the set of\nnamed addresses can be unified. To ensure that named addresses are\nunifiable across renamings, resolution performs unification across named\naddresses using a `Rc>>`: when a named address first\nenters scope in the package graph a `Rc>` is created for it.\nThis refcell is then shared to all uses of the named address _even across\nrenamings_ and when a value is assigned to it, the value must (1) match the\ncurrent value contained within the `Option`, or (2) the `Option` is `None`,\nand the value is placed into the refcell.\n\n## Compilation\n\nThe final stage of the package system is compilation. All logic relating to\nthe final build artifacts, or global environment creation, is contained in\nthe [`./src/compilation`](./src/compilation) directory. The package layout\nfor compiled Move packages is defined in\n[`./src/compilation/package_layout.rs`](./src/compilation/package_layout.rs).\n\nThe [`./src/compilation/build_plan.rs`](./src/compilation/build_plan.rs)\ncontains the logic for driving the compilation of a package and the\ncompilation of all of the package's dependencies given a valid resolution\ngraph. The logic in\n[`./src/compilation/compiled_package.rs`](./src/compilation/compiled_package.rs)\ncontains the definition of the in-memory representation of compiled Move\npackages and other data structures and APIs relating to compiled Move\npackages, along with the logic for compiling a _single_ Move package\nassuming all of its dependencies are already compiled and saved to disk.\nThis is driven by the logic in\n[`./src/compilation/build_plan.rs`](./src/compilation/build_plan.rs). The\ncompilation process is also responsible for generating documentation, ABIs\nand the like, along with determining if a cached version of the\nto-be-built package already exists and if so, if the cached version\ncan be used or if the cached copy is invalid and needs to be recompiled.\n\nOne important thing to note here is that depending on the compilation\nflags, the caching policy may need to be updated and the `compiler_driver`\nfunction that is passed into the compilation process may change. However,\nwhat this function should be is determined by the client of the Move\npackage library. In particular, when testing even if we are recompiling\nwith the same flags we cannot cache the root package as we need to compile\nit to generate the test plan that will be used by the unit test runner\nlater on. This gathering of the test plan is inserted into the compilation\nprocess via the `compiler_driver` function that is passed in by the client.\nIn this case, the [`../move-cli/src/package`](../move-cli/src/package) is\nthe client and it is responsible for supplying the correct function as the\ncompiler driver to collect the test plan and to later pass that to the unit\ntest runner.\n","third_party/move/extensions/move-table-extension/README.md":"This crate contains an extension to the Move language with large-scale storage tables.\n\nIn order to use this extension with the Move CLI and package system, you need to compile with\n`feature = [\"table-extension\"]`.\n\nIn order to use this extension in your adapter, you do something as follows:\n\n```rust\nuse move_core_types::account_address::AccountAddress;\nuse move_stdlib::natives;\nuse move_table_extension::NativeTableContext;\nuse move_vm_runtime::move_vm::MoveVM;\nuse move_vm_runtime::native_functions::NativeContextExtensions;\n\nfn run() {\n let resource_resolver = unimplemented!(); // a resource resolver the adapter provides\n let txn_hash = unimplemented!(); // a unique hash for table creation for this transaction\n let table_resolver = unimplemented!(); // a remote table resolver the adapter provides\n let std_addr = unimplemented!(); // address where to deploy the std lib\n let extension_addr = unimplemented!(); // address where to deploy the table extension\n\n let mut extensions = NativeContextExtensions::default();\n extensions.add(NativeTableContext::new(txn_hash, table_resolver));\n let mut natives = move_stdlib::natives::all_natives(std_addr);\n natives.append(&mut move_table_extension::table_natives(extension_addr));\n let vm = MoveVM::new(natives);\n\n let session = vm.new_session_with_extensions(resource_resolver, extensions);\n let result = session.execute_function(..)?;\n let (change_set, events, extensions) = session.finish_with_extensions()?;\n let table_change_set = extensions.get::().into_change_set();\n\n // Do something with the table change set\n // ...\n}\n```\n","third_party/move/tools/move-cli/README.md":"# Move CLI\n\nThe Move command-line interface (Move CLI) is a tool that provides an easy way to interact with Move, to experiment\nwith writing and running Move code, and to experiment with developing new tools useful\nfor Move development. To reflect this, the Move CLI commands are grouped into\nthree main subcommands:\n* **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.\n* **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.\n* **experimental commands**: are experimental commands that are currently in development.\n\nEvery Move CLI command, with the exception of `package create`, is expected to be run within the context of a [Move package](https://move-language.github.io/move/packages.html).\n\n## Installation\n```shell\n$ cargo install --path move/language/tools/move-cli\n```\nor\n```shell\n$ cargo install --git https://github.com/move-language/move move-cli --branch main\n```\n\nThis will install the `move` binary in your Cargo binary directory. On\nmacOS and Linux this is usually `~/.cargo/bin`. You'll want to make sure\nthis location is in your `PATH` environment variable.\n\nNow you should be able to run the Move CLI:\n\n```shell\n$ move\nMove 0.1.0\nCLI frontend for Move compiler and VM\n\nUSAGE:\n move [FLAGS] [OPTIONS] \n ...\n```\n\nWe'll go through the most common Move CLI commands and flags here, however\nyou can find the complete list of commands available by calling `move\n--help`. Additionally, the complete list of flags and options available\nfor each Move CLI command can be found by passing the `--help` flag to it,\ni.e., `move --help`.\n\n## Package Commands\n\nPackage commands provide wrappers with sane defaults around other commands\nthat are provided either by various Move tools, compiler, or prover.\n\nThe `move new` command will create a new empty Move package:\n```shell\n$ move new # Create a Move package under the current dir\n$ move new -p # Create a Move package under path \n```\n\nFrom within a package's root directory, you can build the modules and/or scripts that you have written in the package with:\n```shell\n$ move build # Builds the Move package you are currently in\n$ move build -p # Builds the Move package at \n```\n\nThe compiled artifacts will by default be stored in the `build` directory. You\ncan change where the build artifacts are saved by passing the optional `--build-dir` flag:\n\n```shell\n$ move build --build-dir # Build current Move package and save artifacts under \n```\n\nYou can verify the specifications in a Move package using the Move Prover with the `prove` command:\n\n```shell\n$ move prove # Verify the specifications in the current package\n$ move prove -p # Verify the specifications in the package at \n```\n\nIn order to run the Move Prover [additional tools need to be\ninstalled](https://github.com/move-language/move/blob/main/language/move-prover/doc/user/install.md).\nInformation on the Move Prover and its configuration options can be found\n[here](https://github.com/move-language/move/blob/main/language/move-prover/doc/user/prover-guide.md)\nand\n[here](https://github.com/move-language/move/blob/main/language/move-prover/doc/user/spec-lang.md).\n\nYou can also run unit tests in a package using the `test` command\n\n```shell\n$ move test # Run Move unit tests in the current package\n$ move test -p # Run Move unit tests in the package at \n```\n## Sandbox Commands\n\nThe sandbox allows you to experiment with writing and running Move code without\nvalidators, a blockchain, or transactions. Persistent data is stored on-disk in\na directory structure that mimics the Move memory model\n\n### Project structure\n\nEach sandbox command is run in the context of a Move package. So let's create a\nMove package that we'll use for the code in this README and `cd` into it:\n\n```shell\n$ move new readme\n$ cd readme\n```\n\n### Compiling and running scripts\n\nLet's first start out with a simple script that prints its [`signer`](https://move-language.github.io/move/signer.html).\nCreate a file named `sources/debug_script.move` and type the following into it:\n\n```rust\n// sources/debug_script.move\nscript {\nuse std::debug;\nfun debug_script(account: signer) {\n debug::print(&account)\n}\n}\n```\n\nBefore we can run this however, we need to import the Move standard library\nnursery in order to have access to the `Debug` module and `Std` [named\naddress](https://move-language.github.io/move/address.html#named-addresses).\nYou can specify dependencies locally, or using a Git URL. Here, we will specify\nit using Git, so add the following to the `Move.toml` file in the `readme`\ndirectory:\n\n```toml\n[addresses]\nstd = \"0x1\" # Specify and assign 0x1 to the named address \"std\"\n\n[dependencies]\nMoveNursery = { git = \"https://github.com/move-language/move.git\", subdir = \"language/move-stdlib/nursery\", rev = \"main\" }\n# ^ ^ ^ ^\n# Git dependency Git clone URL Subdir under git repo (optional) Git revision to use\n```\n\nNow let's try running the script -- the very first time may take some time since the package command will clone the repository at the given URL, but subsequent calls should be fast:\n\n```shell\n$ move sandbox run sources/debug_script.move --signers 0xf\n[debug] (&) { 0000000000000000000000000000000f }\n```\n\nThe `--signers 0xf` argument indicates which account address(es) have signed\noff on the script. Omitting `--signers` or passing multiple signers to this\nsingle-`signer` script will trigger a type error.\n\n### Passing arguments\n\nThe CLI supports passing non-`signer` arguments to `move sandbox run` via `--args`. The following argument types are supported:\n* `bool` literals (`true`, `false`)\n* `u64` literals (e.g., `10`, `58`)\n* `address` literals (e.g., `0x12`, `0x0000000000000000000000000000000f`)\n* hexadecimal strings (e.g., `'x\"0012\"'` will parse as the `vector` value `[00, 12]`)\n* ASCII strings (e.g., `'b\"hi\"'` will parse as the `vector` value `[68, 69]`)\n\n### Publishing new modules\n\nWhen executing a transaction script you'll often want to call into different\nMove modules, like in the example above with the `Debug` module. New modules can\nbe added to the `sources` directory in the package where the CLI is being\ninvoked. You can also add dependencies on other packages to have access to the\nmodules that they define (just like we did with the `Debug` module above). The\n`move sandbox run` command will compile and publish each module in the package, and\nin each of the package's transitive dependencies, before running the given script.\n\nTry saving this code in `sources/Test.move`:\n\n```rust\n// sources/Test.move\nmodule 0x2::Test {\n use std::signer;\n\n struct Resource has key { i: u64 }\n\n public fun publish(account: &signer) {\n move_to(account, Resource { i: 10 })\n }\n\n public fun write(account: &signer, i: u64) acquires Resource {\n borrow_global_mut(signer::address_of(account)).i = i;\n }\n\n public fun unpublish(account: &signer) acquires Resource {\n let Resource { i: _ } = move_from(signer::address_of(account));\n }\n}\n```\n\nNow, try\n\n```shell\n$ move build\n```\n\nThis will cause the CLI to compile and typecheck the modules under\n`sources`, but it won't publish the module bytecode under `storage`. You can\ncompile and publish the module by running the `move sandbox publish` command\n(here we pass the `-v` or verbose flag to get a better understanding of what's\nhappening):\n\n```shell\n$ move sandbox publish -v\nFound 1 modules\nPublishing a new module 00000000000000000000000000000002::Test (wrote 253 bytes)\nWrote 253 bytes of module ID's and code\n```\n\nNow, if we take a look under `storage`, we will see the published bytecode\nfor our `Test` module:\n\n```shell\n$ ls storage/0x00000000000000000000000000000002/modules\nTest.mv\n```\n\nWe can also inspect the compiled bytecode in storage using `move sandbox view`:\n\n```shell\n$ move sandbox view storage/0x00000000000000000000000000000002/modules/Test.mv\nmodule 2.Test {\nstruct Resource has key {\n i: u64\n}\n\npublic publish() {\n 0: MoveLoc[0](Arg0: &signer)\n 1: LdU64(10)\n 2: Pack[0](Resource)\n 3: MoveTo[0](Resource)\n 4: Ret\n}\npublic unpublish() {\n 0: MoveLoc[0](Arg0: &signer)\n 1: Call[3](address_of(&signer): address)\n 2: MoveFrom[0](Resource)\n 3: Unpack[0](Resource)\n 4: Pop\n 5: Ret\n}\npublic write() {\n 0: CopyLoc[1](Arg1: u64)\n 1: MoveLoc[0](Arg0: &signer)\n 2: Call[3](address_of(&signer): address)\n 3: MutBorrowGlobal[0](Resource)\n 4: MutBorrowField[0](Resource.i: u64)\n 5: WriteRef\n 6: Ret\n}\n}\n```\n\nYou can also look at the compiled bytecode before publishing to `storage` by\nrunning either `move disassemble --name ` or `move\ndisassemble --name --interactive` to interactively inspect the\nbytecode and how it relates to the Move source code:\n\n```shell\n$ move disassemble --name Test --interactive # You can quit by pressing \"q\"\n$ move disassemble --name Test\n// Move bytecode v4\nmodule 2.Test {\nstruct Resource has key {\n i: u64\n}\n\npublic publish() {\nB0:\n 0: MoveLoc[0](account: &signer)\n 1: LdU64(10)\n 2: Pack[0](Resource)\n 3: MoveTo[0](Resource)\n 4: Ret\n}\npublic unpublish() {\nB0:\n 0: MoveLoc[0](account: &signer)\n 1: Call[3](address_of(&signer): address)\n 2: MoveFrom[0](Resource)\n 3: Unpack[0](Resource)\n 4: Pop\n 5: Ret\n}\npublic write() {\nB0:\n 0: CopyLoc[1](i: u64)\n 1: MoveLoc[0](account: &signer)\n 2: Call[3](address_of(&signer): address)\n 3: MutBorrowGlobal[0](Resource)\n 4: MutBorrowField[0](Resource.i: u64)\n 5: WriteRef\n 6: Ret\n}\n}\n```\n\n### Updating state\n\nLet's exercise our new `Test` module by running the following script:\n\n```rust\n// sources/test_script.move\nscript {\nuse 0x2::Test;\nfun test_script(account: signer) {\n Test::publish(&account)\n}\n}\n```\n\nThis script invokes the `publish` function of our `Test` module, which will\npublish a resource of type `Test::Resource` under the signer's account.\nLet's first see what this script will change without committing those\nchanges first. We can do this by passing the `--dry-run` flag:\n\n```shell\n$ move sandbox run sources/test_script.move --signers 0xf -v --dry-run\nCompiling transaction script...\nChanged resource(s) under 1 address(es):\n Changed 1 resource(s) under address 0000000000000000000000000000000f:\n Added type 0x2::Test::Resource: [10, 0, 0, 0, 0, 0, 0, 0] (wrote 40 bytes)\nWrote 40 bytes of resource ID's and data\n key 0x2::Test::Resource {\n i: 10\n }\nDiscarding changes; re-run without --dry-run if you would like to keep them.\n```\n\nEverything looks good, so we can run this again, but this time commit the\nchanges by removing the `--dry-run` flag:\n\n```shell\n$ move sandbox run sources/test_script.move --signers 0xf -v\nCompiling transaction script...\nChanged resource(s) under 1 address(es):\n Changed 1 resource(s) under address 0000000000000000000000000000000f:\n Added type 0x2::Test::Resource: [10, 0, 0, 0, 0, 0, 0, 0] (wrote 40 bytes)\nWrote 40 bytes of resource ID's and data\n key 0x2::Test::Resource {\n i: 10\n }\n```\n\nWhile the verbose flag used above (`-v`) shows resource changes, it is also\npossible to view them manually.\nWe can inspect the newly published resource using `move sandbox view` since\nthe change has been committed:\n\n```shell\n$ move sandbox view storage/0x0000000000000000000000000000000f/resources/0x00000000000000000000000000000002::Test::Resource.bcs\nkey 0x2::Test::Resource {\n i: 10\n}\n```\n\n#### Cleaning state\n\nSince state persists from one call to the Move CLI to another, there will\nfrequently be times where you want to start again at a clean state. This\ncan be done using the `move sandbox clean` command which will remove the\n`storage` and `build` directories:\n\n```shell\n$ move sandbox view storage/0x0000000000000000000000000000000f/resources/0x00000000000000000000000000000002::Test::Resource.bcs\nresource 0x2::Test::Resource {\n i: 10\n}\n$ move sandbox clean\n$ move sandbox view storage/0x0000000000000000000000000000000f/resources/0x00000000000000000000000000000002::Test::Resource.bcs\nError: `move sandbox view ` must point to a valid file under storage\n```\n\n### Expected Value Testing with the Move CLI\n\nAs mentioned previously, Move has a unit testing framework. However, unit tests\ncannot test everything -- in particular testing for events cannot be easily\ndone. To help with writing tests that need to check for events, and expect\nspecific states, the Move CLI also has a built-in expected-value testing\nframework. Each test is run independently in its own sandbox so state does not\npersist from one test to another.\n\nEach test is structured as a Move package along with an additional `args.txt` file that\nspecifies a sequence of Move CLI commands that should be run in that\ndirectory.\nAdditionally, there must be an `args.exp` file that contain the expected\noutput from running the sequence of Move CLI commands specified in the\n`args.txt` file for that test.\n\nFor example, if we wanted to create a Move CLI test that reran all of the\ncommands that we've seen so far, we could do so by adding an `args.txt`\nto the `readme` directory that we created at the start and that we've been\nadding scripts and modules to:\n\n```\nreadme/\n├── args.txt\n├── Move.toml\n└── sources\n ├── debug_script.move\n ├── Test.move\n └── test_script.move\n```\n\nAnd, where the `args.txt` file contains the following Move CLI commands:\n\n```shell\n$ cd ..\n$ cat readme/args.txt\n## Arg files can have comments!\nsandbox run sources/debug_script.move --signers 0xf\nsandbox run sources/debug_script.move --signers 0xf\nbuild\nsandbox publish\nsandbox view storage/0x00000000000000000000000000000002/modules/Test.mv\nsandbox run sources/test_script.move --signers 0xf -v\nsandbox view storage/0x0000000000000000000000000000000f/resources/0x00000000000000000000000000000002::Test::Resource.bcs\n```\n\nWe can then use the `move sandbox test` command and point it at the `readme` directory to run each of these\nMove CLI commands for us in sequence:\n\n```shell\n$ move sandbox exp-test -p readme\n...\n0 / 1 test(s) passed.\nError: 1 / 1 test(s) failed.\n```\n\nHowever, as we see this test will fail since there is no `args.exp` file for the test\nyet. We can generate this expectation file by setting the `UPDATE_BASELINE`\nenvironment variable when running the test:\n\n```shell\n$ UPDATE_BASELINE=1 move sandbox exp-test -p readme\n1 / 1 test(s) passed.\n```\n\nThere should now be an `args.exp` file under the `readme` directory that\ncontains the expected output of running the sequence of Move CLI commands\nin the `args.txt` file:\n\n```shell\n$ cat readme/args.exp\nCommand `sandbox run sources/debug_script.move --signers 0xf`:\n[debug] (&) { 0000000000000000000000000000000f }\nCommand `sandbox run sources/debug_script.move --signers 0xf --mode bare`:\n...\n```\n\n#### Testing with code coverage tracking\n\nCode coverage has been an important metric in software testing. In Move CLI expected value tests, we\naddress the need for code coverage information with an additional flag,\n`--track-cov`, that can be passed to the `move sandbox exp-test` command.\n\nNote: To view coverage information, the Move CLI must be installed with the `--debug` flag;\ni.e., `cargo install --debug --path move/language/tools/move-cli`.\n\nUsing our running example to illustrate:\n```shell\n$ move sandbox exp-test -p readme --track-cov\n1 / 1 test(s) passed.\nModule 00000000000000000000000000000002::Test\n fun publish\n total: 5\n covered: 5\n % coverage: 100.00\n fun unpublish\n total: 6\n covered: 0\n % coverage: 0.00\n fun write\n total: 7\n covered: 0\n % coverage: 0.00\n>>> % Module coverage: 27.78\n```\n\nThe output indicates that not only the test is passed, but also that 100%\ninstruction coverage is observed in the `publish` funciton. This is expected\nas the whole purpose of our `test_script.move` is to run the `publish` function.\nAt the same time, the other two functions, `unpublish` and `write`, are never\nexecuted, making the average coverage 27.78% for the whole `Test` module.\n\nInternally, Move CLI uses the tracing feature provided by the Move VM to record\nwhich instructions in the compiled bytecode are executed and uses this\ninformation to calculate code coverage. Instruction coverage in Move can\nusually serve the purpose of line coverage in common C/C++/Rust coverage\ntracking tools.\n\nNote that the coverage information is aggregated across multiple `run` commands\nin `args.txt`. To illustrate this, suppose that we have another test script,\n`test_unpublish_script.move`, under `readme/sources` with the following\ncontent:\n\n```rust\nscript {\nuse 0x2::Test;\nfun test_unpublish_script(account: signer) {\n Test::unpublish(&account)\n}\n}\n```\n\nWe further add a new command to the end of `args.txt`\n(`args.exp` needs to be updated too).\n```shell\nsandbox run sources/test_unpublish_script.move --signers 0xf -v\n```\n\nNow we can re-test the `readme` again\n```shell\n$ move sandbox exp-test -p readme --track-cov\n1 / 1 test(s) passed.\nModule 00000000000000000000000000000002::Test\n fun publish\n total: 5\n covered: 5\n % coverage: 100.00\n fun unpublish\n total: 6\n covered: 6\n % coverage: 100.00\n fun write\n total: 7\n covered: 0\n % coverage: 0.00\n>>> % Module coverage: 61.11\n```\n\nThis time, note that the `unpublish` function is 100% covered too and the\noverall module coverage is boosted to 61.11%.\n\n### Detecting breaking changes\n\nThe `move sandbox publish` command automatically detects when upgrading a module may lead to a breaking change.\nThere are two kinds of breaking changes:\n\n* Linking compatibility (e.g., removing or changing the signature of a public function that is invoked by other modules, removing a\nstruct or resource type used by other modules)\n* Layout compatibility (e.g., adding/removing a resource or struct field)\n\nThe breaking changes analysis performed by `move sandbox publish` is necessarily conservative. For example, say we `move sandbox publish` the following\nmodule:\n\n```\naddress 0x2 {\nmodule M {\n struct S has key { f: u64, g: u64 }\n}\n}\n```\n\nand then wish to upgrade it to the following:\n\n```\naddress 0x2 {\nmodule M {\n struct S has key { f: u64 }\n}\n}\n```\n\nRunning `move sandbox publish` on this new version will fail:\n\n```\nBreaking change detected--publishing aborted. Re-run with --ignore-breaking-changes to publish anyway.\nError: Layout API for structs of module 00000000000000000000000000000002::M has changed. Need to do a data migration of published structs\n```\n\nIn this case, we know we have not published any instances of `S` in global storage, so it is safe to re-run `move sandbox publish --ignore-breaking-changes` (as recommended).\nWe can double-check that this was not a breaking change by running `move sandbox doctor`.\nThis handy command runs exhaustive sanity checks on global storage to detect any breaking changes that occurred in the past:\n* All modules pass the bytecode verifier\n* All modules link against their dependencies\n* All resources deserialize according to their declared types\n* All events deserialize according to their declared types\n","third_party/move/tools/move-unit-test/README.md":"---\nid: move-unit-test\ntitle: Move Unit Testing Framework\ncustom_edit_url: https://github.com/move-language/move/edit/main/language/tools/move-unit-test/README.md\n---\n\n# Summary\n\nThis crate defines the core logic for running and reporting Move unit\ntests. Move unit testing is made up of two main components; a test runner,\nand a test reporter.\n\nIt's important to also note here that unit tests can be run using the\n[stackless bytecode interpreter](../../move-prover/interpreter). If the\nunit tests are run with the stackless bytecode interpreter and the test\nreturns a value, then the result of executing the unit test with the Move\nVM and the result of the interpreter will be compared and an error will\nbe raised if they are not equal.\n\nDetailed information on how to use unit tests as a user of Move can be\nfound [here](https://move-language.github.io/move/unit-testing.html).\n\n## Test Runner\n\nThe test runner consumes a\n[`TestPlan`](../../move-compiler/src/unit_test/mod.rs): this is a\ndatastructure that is built by the Move compiler, based on source `#[test]`\nattributes. At a high level, this test plan consists of:\n1. A list of `ModuleTestPlan`s for each non-dependency module. A\n `ModuleTestPlan` consists of a list of unit tests declared in a module,\n along with its arguments and whether the unit test is an expected\n failure or not.\n2. Compiled modules for each source module, along with compiled modules for\n all transitive dependencies.\n3. The source text and source maps for every source and transitive dependency.\n\nThe test runner takes this `TestPlan` along with various configuration\noptions (e.g., number of threads). From this information the test runner\ncreates an initial test state consisting solely of the modules in bullet\n(2) above. This will be the same initial state for all unit tests.\n\nAfter constructing this initial state, a work queue of `ModuleTestPlan`s is\npassed to a [`rayon`](https://docs.rs/rayon/latest/rayon/) threadpool to\nexecute. After the execution of each test a `PASS`, `FAIL` or `TIMEOUT` is\nreported to the writer (usually `std::io::stdout`) as soon as the test's\nresult is known. The result of running tests in a `ModuleTestPlan` is a\nmapping of failing and passing tests (where failing means that the tests\nfailed when it was expected to fail, or vis versa) along with profiling\ninformation and failure information if applicable. These test statistics\nfor each module are combined in parallel and produce a `TestResults` data\nstructure.\n\n## Test Reporter\n\nAfter all of the unit tests have been run and a `TestResults` data\nstructure has been created, the test reporter will iterate through the test\nresults, and will use the data in the `TestFailure` info along with the\nsource maps and source text in the test plan to display source-level error\nmessages for any failing tests.\n\nDepending on the options passed to the unit testing framework, additional\ninfo, such as the global storage state at the point of error for each\nfailing test, or the execution time and number of instructions for each\ntest may be display at the end of a test run.\n","third_party/move/move-examples/diem-framework/move-packages/core/README.md":"This folder contains a Move package consisting of core Move modules defining functionalities needed by\nany Diem-based blockchains. To start your own Diem-based blockchain, you can create a Move package that\ndepends on this core package and write your own wrapper modules for the account module as well as the\non-chain configuration modules. [`experimental` folder](../experimental) provides an example of such\nMove package.\n\nNext we briefly describe how to write the wrapper modules and how Move's powerful type system can provide flexibility\nas well as safety for your chain.\n\nYou will need to write wrapper modules for the following core modules:\n- Account\n- CoreGenesis\n- DiemConsensusConfig\n- DiemSystem\n- DiemVersion\n- DiemVMConfig\n- ParallelExecutionConfig\n- ValidatorConfig\n- ValidatorOperatorConfig\n\n\nEvery module in this list contains the following resources and functions:\n- A chain marker resource with a `phantom T` type parameter\n- An initialization function that has to be called during chain-specific genesis and publishes a chain marker resource under\n `@CoreResources` address as well as any relevant configuration resources\n- At least one setter function that requires a `Cap` as parameter and modifies the configuration resource(s).\n And at the beginning of the function we check the existence of the chain marker resource.\n\n#### Why is the chain marker resource needed?\n\nWe want to provide the safety guarantee that only the authorized wrapper module can define access\ncontrol policies for the resources. Therefore, we need to make sure that only the wrapper module can call the public\nsetter functions. However, we are designing for wrapper modules that don't even exist right now, so we have to somehow\n\"register\" the wrapper module at the chain-specific genesis. The solution to this question is the chain marker resource.\nThis resource has a phantom type parameter that should be instantiated with a type owned by the wrapper module such as\n`ExperimentalVersion` resource. Each setter function requires a capability parameter instantiated with this type. Since\nthe acquisition of this capability requires a value of this witness type and this type is owned by the wrapper module,\nwe know for sure that only the wrapper module can decide who or which module is allowed to modify the configurations.\n\n#### How to write wrapper modules?\n\nRead `DiemVersion.move` and then `ExperimentalVersion.move` to get the idea.\n","aptos-move/move-examples/large_packages/README.md":"# Moved to https://aptos-labs.github.io/framework-book/aptos-experimental/large_packages.html\n"},"files":{"third_party/move/extensions/README.md":"This tree contains extensions to the Move core language and runtime. Those extensions are not enabled by\ndefault but can be integrated into a Move-based environment following the instructions found for each individual\nextension.\n\nSome extensions may eventually become part of the core language after some period of stabilization.\n","third_party/move/tools/README.md":"---\nid: tools\ntitle: Move Tools\ncustom_edit_url: https://github.com/move-language/move/edit/main/language/tools/README.md\n---\n\n# Summary\n\nMove has a number of tools associated with it. This directory contains all,\nor almost all of them. The following crates in this directory are libraries\nthat are used by the [`move-cli`](./move-cli) `package` subcommand:\n\n* `move-bytecode-viewer`\n* `move-disassembler`\n* `move-explain`\n* `move-unit-test`\n* `move-package`\n* `move-coverage`\n\nIn this sense each of these crates defines the core logic for a specific\npackage command, e.g., how to run and report unit tests, or collect and\ndisplay test coverage information. However, the Move CLI is responsible for\nstitching these commands together, e.g., when running a move unit test the\nMove CLI is responsible for first making sure the package was built in\n`test` mode ( using the `move-package` library), collecting the test plan\nto feed to the `move-unit-test` library, and returning a non-zero error\ncode if a test fails.\n\nGenerally, if you want to see how various tools interact with each other,\nor how a normal Move user would interact with these tools, you should first\nlook at the Move CLI (specifically the `package` subdirectory/command) as\nthat is responsible for stitching everything together. If you are looking\nfor where the logic for a specific tool is defined, this is most likely in\nthe specific crate for that tool (e.g., if you want to see how TUIs are\nhandled for the `move-bytecode-viewer` that's defined in the\n`move-bytecode-viewer` crate, and not the `move-cli` crate).\n\nSome of the crates mentioned above are also binaries at the moment, however\nthey should all be able to be made libaries only, with the possible\nexception of the `move-coverage` crate. The primary reason for this, is\nthat this tool can collect and report test coverage statistics across\nmultiple packages, and multiple runs over a package. This functionality is\nimportant if you have a large functional test suite such as Diem's and want\nto gather coverage information across all of them.\n\nThe `move-resource-viewer`, and `read-write-set` similarly are library\ncrates that are used by and exposed by the Move CLI, but not through the\n`package` subcommand.\n\nThe `move-bytecode-utils` crates holds general\nutilities for working with Move bytecode, e.g., computing the dependency\norder for modules.\n","third_party/move/tools/move-package/README.md":"---\nid: move-package\ntitle: Move Package\ncustom_edit_url: https://github.com/move-language/move/edit/main/language/tools/move-package/README.md\n---\n\n# Summary\n\nThe Move package crate contains the logic for parsing, resolving, and\nbuilding Move packages. It is meant to be used as a library, both for\nbuilding packages (e.g., by the Move CLI), or by other applications that\nmay be working with Move packages. The package system is split into three\nmain phases: parsing, resolution, and compilation.\n\n## Parsing and Manifest Layout\n\nThe parsing and manifest layout logic is defined in the\n[`./src/source_package`](./src/source_package) directory. This defines the\nlayout and the set of required and optional directories for a Move package\nin [`./src/source_package/layout.rs`](./src/source_package/layout.rs), it\ndefines the format of the parsed Move package manifest (\"`Move.toml`\") in\n[`./src/source_package/parsed_manifest.rs`](./src/source_package/parsed_manifest.rs),\nand it defines the parser for the Move package manifest in\n[`./src/source_package/manifest_parser.rs`](./src/source_package/manifest_parser.rs).\nNote that we don't have a tokenizer/lexer as we use the TOML lexer. This\nalso resolves git dependencies to where they will live on the local file\nsystem (but does not clone them).\n\n## Resolution\n\nThe resolution phase is responsible for resolving all packages and building\nthe package graph which represents the dependency relations between\npackages. It is also responsible for ensuring that all named addresses have\na value assigned to them, and that there are no conflicting assignments.\nThe package graph is rooted at the package being built and is a DAG.\n\nWhen building the package graph we do the following conceptual operations:\nverify that dependencies exist at the declared locations, that their\npackage names and source digests match (if applicable), clone git\ndependencies if they don't already exist locally, build a dependency graph\nof Move packages and ensure this forms a DAG, compute an\nassignment for each named address in each Move package in the package\ngraph, and ensure that the resulting named address assignment is valid.\n\nAll of the above steps are fairly straightforward, with the possible\nexception of named addresses: each package will have a set of in-scope\nnamed addresses. The set of in-scope named addresses for a package `P` is\ndefined as the transitive closure of all named addresses in the\ndependencies of `P`. Additionally, a package can rename named addresses\nthat are in-scope as long as the final assignment of a value to the set of\nnamed addresses can be unified. To ensure that named addresses are\nunifiable across renamings, resolution performs unification across named\naddresses using a `Rc>>`: when a named address first\nenters scope in the package graph a `Rc>` is created for it.\nThis refcell is then shared to all uses of the named address _even across\nrenamings_ and when a value is assigned to it, the value must (1) match the\ncurrent value contained within the `Option`, or (2) the `Option` is `None`,\nand the value is placed into the refcell.\n\n## Compilation\n\nThe final stage of the package system is compilation. All logic relating to\nthe final build artifacts, or global environment creation, is contained in\nthe [`./src/compilation`](./src/compilation) directory. The package layout\nfor compiled Move packages is defined in\n[`./src/compilation/package_layout.rs`](./src/compilation/package_layout.rs).\n\nThe [`./src/compilation/build_plan.rs`](./src/compilation/build_plan.rs)\ncontains the logic for driving the compilation of a package and the\ncompilation of all of the package's dependencies given a valid resolution\ngraph. The logic in\n[`./src/compilation/compiled_package.rs`](./src/compilation/compiled_package.rs)\ncontains the definition of the in-memory representation of compiled Move\npackages and other data structures and APIs relating to compiled Move\npackages, along with the logic for compiling a _single_ Move package\nassuming all of its dependencies are already compiled and saved to disk.\nThis is driven by the logic in\n[`./src/compilation/build_plan.rs`](./src/compilation/build_plan.rs). The\ncompilation process is also responsible for generating documentation, ABIs\nand the like, along with determining if a cached version of the\nto-be-built package already exists and if so, if the cached version\ncan be used or if the cached copy is invalid and needs to be recompiled.\n\nOne important thing to note here is that depending on the compilation\nflags, the caching policy may need to be updated and the `compiler_driver`\nfunction that is passed into the compilation process may change. However,\nwhat this function should be is determined by the client of the Move\npackage library. In particular, when testing even if we are recompiling\nwith the same flags we cannot cache the root package as we need to compile\nit to generate the test plan that will be used by the unit test runner\nlater on. This gathering of the test plan is inserted into the compilation\nprocess via the `compiler_driver` function that is passed in by the client.\nIn this case, the [`../move-cli/src/package`](../move-cli/src/package) is\nthe client and it is responsible for supplying the correct function as the\ncompiler driver to collect the test plan and to later pass that to the unit\ntest runner.\n","third_party/move/extensions/move-table-extension/README.md":"This crate contains an extension to the Move language with large-scale storage tables.\n\nIn order to use this extension with the Move CLI and package system, you need to compile with\n`feature = [\"table-extension\"]`.\n\nIn order to use this extension in your adapter, you do something as follows:\n\n```rust\nuse move_core_types::account_address::AccountAddress;\nuse move_stdlib::natives;\nuse move_table_extension::NativeTableContext;\nuse move_vm_runtime::move_vm::MoveVM;\nuse move_vm_runtime::native_functions::NativeContextExtensions;\n\nfn run() {\n let resource_resolver = unimplemented!(); // a resource resolver the adapter provides\n let txn_hash = unimplemented!(); // a unique hash for table creation for this transaction\n let table_resolver = unimplemented!(); // a remote table resolver the adapter provides\n let std_addr = unimplemented!(); // address where to deploy the std lib\n let extension_addr = unimplemented!(); // address where to deploy the table extension\n\n let mut extensions = NativeContextExtensions::default();\n extensions.add(NativeTableContext::new(txn_hash, table_resolver));\n let mut natives = move_stdlib::natives::all_natives(std_addr);\n natives.append(&mut move_table_extension::table_natives(extension_addr));\n let vm = MoveVM::new(natives);\n\n let session = vm.new_session_with_extensions(resource_resolver, extensions);\n let result = session.execute_function(..)?;\n let (change_set, events, extensions) = session.finish_with_extensions()?;\n let table_change_set = extensions.get::().into_change_set();\n\n // Do something with the table change set\n // ...\n}\n```\n","third_party/move/tools/move-cli/README.md":"# Move CLI\n\nThe Move command-line interface (Move CLI) is a tool that provides an easy way to interact with Move, to experiment\nwith writing and running Move code, and to experiment with developing new tools useful\nfor Move development. To reflect this, the Move CLI commands are grouped into\nthree main subcommands:\n* **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.\n* **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.\n* **experimental commands**: are experimental commands that are currently in development.\n\nEvery Move CLI command, with the exception of `package create`, is expected to be run within the context of a [Move package](https://move-language.github.io/move/packages.html).\n\n## Installation\n```shell\n$ cargo install --path move/language/tools/move-cli\n```\nor\n```shell\n$ cargo install --git https://github.com/move-language/move move-cli --branch main\n```\n\nThis will install the `move` binary in your Cargo binary directory. On\nmacOS and Linux this is usually `~/.cargo/bin`. You'll want to make sure\nthis location is in your `PATH` environment variable.\n\nNow you should be able to run the Move CLI:\n\n```shell\n$ move\nMove 0.1.0\nCLI frontend for Move compiler and VM\n\nUSAGE:\n move [FLAGS] [OPTIONS] \n ...\n```\n\nWe'll go through the most common Move CLI commands and flags here, however\nyou can find the complete list of commands available by calling `move\n--help`. Additionally, the complete list of flags and options available\nfor each Move CLI command can be found by passing the `--help` flag to it,\ni.e., `move --help`.\n\n## Package Commands\n\nPackage commands provide wrappers with sane defaults around other commands\nthat are provided either by various Move tools, compiler, or prover.\n\nThe `move new` command will create a new empty Move package:\n```shell\n$ move new # Create a Move package under the current dir\n$ move new -p # Create a Move package under path \n```\n\nFrom within a package's root directory, you can build the modules and/or scripts that you have written in the package with:\n```shell\n$ move build # Builds the Move package you are currently in\n$ move build -p # Builds the Move package at \n```\n\nThe compiled artifacts will by default be stored in the `build` directory. You\ncan change where the build artifacts are saved by passing the optional `--build-dir` flag:\n\n```shell\n$ move build --build-dir # Build current Move package and save artifacts under \n```\n\nYou can verify the specifications in a Move package using the Move Prover with the `prove` command:\n\n```shell\n$ move prove # Verify the specifications in the current package\n$ move prove -p # Verify the specifications in the package at \n```\n\nIn order to run the Move Prover [additional tools need to be\ninstalled](https://github.com/move-language/move/blob/main/language/move-prover/doc/user/install.md).\nInformation on the Move Prover and its configuration options can be found\n[here](https://github.com/move-language/move/blob/main/language/move-prover/doc/user/prover-guide.md)\nand\n[here](https://github.com/move-language/move/blob/main/language/move-prover/doc/user/spec-lang.md).\n\nYou can also run unit tests in a package using the `test` command\n\n```shell\n$ move test # Run Move unit tests in the current package\n$ move test -p # Run Move unit tests in the package at \n```\n## Sandbox Commands\n\nThe sandbox allows you to experiment with writing and running Move code without\nvalidators, a blockchain, or transactions. Persistent data is stored on-disk in\na directory structure that mimics the Move memory model\n\n### Project structure\n\nEach sandbox command is run in the context of a Move package. So let's create a\nMove package that we'll use for the code in this README and `cd` into it:\n\n```shell\n$ move new readme\n$ cd readme\n```\n\n### Compiling and running scripts\n\nLet's first start out with a simple script that prints its [`signer`](https://move-language.github.io/move/signer.html).\nCreate a file named `sources/debug_script.move` and type the following into it:\n\n```rust\n// sources/debug_script.move\nscript {\nuse std::debug;\nfun debug_script(account: signer) {\n debug::print(&account)\n}\n}\n```\n\nBefore we can run this however, we need to import the Move standard library\nnursery in order to have access to the `Debug` module and `Std` [named\naddress](https://move-language.github.io/move/address.html#named-addresses).\nYou can specify dependencies locally, or using a Git URL. Here, we will specify\nit using Git, so add the following to the `Move.toml` file in the `readme`\ndirectory:\n\n```toml\n[addresses]\nstd = \"0x1\" # Specify and assign 0x1 to the named address \"std\"\n\n[dependencies]\nMoveNursery = { git = \"https://github.com/move-language/move.git\", subdir = \"language/move-stdlib/nursery\", rev = \"main\" }\n# ^ ^ ^ ^\n# Git dependency Git clone URL Subdir under git repo (optional) Git revision to use\n```\n\nNow let's try running the script -- the very first time may take some time since the package command will clone the repository at the given URL, but subsequent calls should be fast:\n\n```shell\n$ move sandbox run sources/debug_script.move --signers 0xf\n[debug] (&) { 0000000000000000000000000000000f }\n```\n\nThe `--signers 0xf` argument indicates which account address(es) have signed\noff on the script. Omitting `--signers` or passing multiple signers to this\nsingle-`signer` script will trigger a type error.\n\n### Passing arguments\n\nThe CLI supports passing non-`signer` arguments to `move sandbox run` via `--args`. The following argument types are supported:\n* `bool` literals (`true`, `false`)\n* `u64` literals (e.g., `10`, `58`)\n* `address` literals (e.g., `0x12`, `0x0000000000000000000000000000000f`)\n* hexadecimal strings (e.g., `'x\"0012\"'` will parse as the `vector` value `[00, 12]`)\n* ASCII strings (e.g., `'b\"hi\"'` will parse as the `vector` value `[68, 69]`)\n\n### Publishing new modules\n\nWhen executing a transaction script you'll often want to call into different\nMove modules, like in the example above with the `Debug` module. New modules can\nbe added to the `sources` directory in the package where the CLI is being\ninvoked. You can also add dependencies on other packages to have access to the\nmodules that they define (just like we did with the `Debug` module above). The\n`move sandbox run` command will compile and publish each module in the package, and\nin each of the package's transitive dependencies, before running the given script.\n\nTry saving this code in `sources/Test.move`:\n\n```rust\n// sources/Test.move\nmodule 0x2::Test {\n use std::signer;\n\n struct Resource has key { i: u64 }\n\n public fun publish(account: &signer) {\n move_to(account, Resource { i: 10 })\n }\n\n public fun write(account: &signer, i: u64) acquires Resource {\n borrow_global_mut(signer::address_of(account)).i = i;\n }\n\n public fun unpublish(account: &signer) acquires Resource {\n let Resource { i: _ } = move_from(signer::address_of(account));\n }\n}\n```\n\nNow, try\n\n```shell\n$ move build\n```\n\nThis will cause the CLI to compile and typecheck the modules under\n`sources`, but it won't publish the module bytecode under `storage`. You can\ncompile and publish the module by running the `move sandbox publish` command\n(here we pass the `-v` or verbose flag to get a better understanding of what's\nhappening):\n\n```shell\n$ move sandbox publish -v\nFound 1 modules\nPublishing a new module 00000000000000000000000000000002::Test (wrote 253 bytes)\nWrote 253 bytes of module ID's and code\n```\n\nNow, if we take a look under `storage`, we will see the published bytecode\nfor our `Test` module:\n\n```shell\n$ ls storage/0x00000000000000000000000000000002/modules\nTest.mv\n```\n\nWe can also inspect the compiled bytecode in storage using `move sandbox view`:\n\n```shell\n$ move sandbox view storage/0x00000000000000000000000000000002/modules/Test.mv\nmodule 2.Test {\nstruct Resource has key {\n i: u64\n}\n\npublic publish() {\n 0: MoveLoc[0](Arg0: &signer)\n 1: LdU64(10)\n 2: Pack[0](Resource)\n 3: MoveTo[0](Resource)\n 4: Ret\n}\npublic unpublish() {\n 0: MoveLoc[0](Arg0: &signer)\n 1: Call[3](address_of(&signer): address)\n 2: MoveFrom[0](Resource)\n 3: Unpack[0](Resource)\n 4: Pop\n 5: Ret\n}\npublic write() {\n 0: CopyLoc[1](Arg1: u64)\n 1: MoveLoc[0](Arg0: &signer)\n 2: Call[3](address_of(&signer): address)\n 3: MutBorrowGlobal[0](Resource)\n 4: MutBorrowField[0](Resource.i: u64)\n 5: WriteRef\n 6: Ret\n}\n}\n```\n\nYou can also look at the compiled bytecode before publishing to `storage` by\nrunning either `move disassemble --name ` or `move\ndisassemble --name --interactive` to interactively inspect the\nbytecode and how it relates to the Move source code:\n\n```shell\n$ move disassemble --name Test --interactive # You can quit by pressing \"q\"\n$ move disassemble --name Test\n// Move bytecode v4\nmodule 2.Test {\nstruct Resource has key {\n i: u64\n}\n\npublic publish() {\nB0:\n 0: MoveLoc[0](account: &signer)\n 1: LdU64(10)\n 2: Pack[0](Resource)\n 3: MoveTo[0](Resource)\n 4: Ret\n}\npublic unpublish() {\nB0:\n 0: MoveLoc[0](account: &signer)\n 1: Call[3](address_of(&signer): address)\n 2: MoveFrom[0](Resource)\n 3: Unpack[0](Resource)\n 4: Pop\n 5: Ret\n}\npublic write() {\nB0:\n 0: CopyLoc[1](i: u64)\n 1: MoveLoc[0](account: &signer)\n 2: Call[3](address_of(&signer): address)\n 3: MutBorrowGlobal[0](Resource)\n 4: MutBorrowField[0](Resource.i: u64)\n 5: WriteRef\n 6: Ret\n}\n}\n```\n\n### Updating state\n\nLet's exercise our new `Test` module by running the following script:\n\n```rust\n// sources/test_script.move\nscript {\nuse 0x2::Test;\nfun test_script(account: signer) {\n Test::publish(&account)\n}\n}\n```\n\nThis script invokes the `publish` function of our `Test` module, which will\npublish a resource of type `Test::Resource` under the signer's account.\nLet's first see what this script will change without committing those\nchanges first. We can do this by passing the `--dry-run` flag:\n\n```shell\n$ move sandbox run sources/test_script.move --signers 0xf -v --dry-run\nCompiling transaction script...\nChanged resource(s) under 1 address(es):\n Changed 1 resource(s) under address 0000000000000000000000000000000f:\n Added type 0x2::Test::Resource: [10, 0, 0, 0, 0, 0, 0, 0] (wrote 40 bytes)\nWrote 40 bytes of resource ID's and data\n key 0x2::Test::Resource {\n i: 10\n }\nDiscarding changes; re-run without --dry-run if you would like to keep them.\n```\n\nEverything looks good, so we can run this again, but this time commit the\nchanges by removing the `--dry-run` flag:\n\n```shell\n$ move sandbox run sources/test_script.move --signers 0xf -v\nCompiling transaction script...\nChanged resource(s) under 1 address(es):\n Changed 1 resource(s) under address 0000000000000000000000000000000f:\n Added type 0x2::Test::Resource: [10, 0, 0, 0, 0, 0, 0, 0] (wrote 40 bytes)\nWrote 40 bytes of resource ID's and data\n key 0x2::Test::Resource {\n i: 10\n }\n```\n\nWhile the verbose flag used above (`-v`) shows resource changes, it is also\npossible to view them manually.\nWe can inspect the newly published resource using `move sandbox view` since\nthe change has been committed:\n\n```shell\n$ move sandbox view storage/0x0000000000000000000000000000000f/resources/0x00000000000000000000000000000002::Test::Resource.bcs\nkey 0x2::Test::Resource {\n i: 10\n}\n```\n\n#### Cleaning state\n\nSince state persists from one call to the Move CLI to another, there will\nfrequently be times where you want to start again at a clean state. This\ncan be done using the `move sandbox clean` command which will remove the\n`storage` and `build` directories:\n\n```shell\n$ move sandbox view storage/0x0000000000000000000000000000000f/resources/0x00000000000000000000000000000002::Test::Resource.bcs\nresource 0x2::Test::Resource {\n i: 10\n}\n$ move sandbox clean\n$ move sandbox view storage/0x0000000000000000000000000000000f/resources/0x00000000000000000000000000000002::Test::Resource.bcs\nError: `move sandbox view ` must point to a valid file under storage\n```\n\n### Expected Value Testing with the Move CLI\n\nAs mentioned previously, Move has a unit testing framework. However, unit tests\ncannot test everything -- in particular testing for events cannot be easily\ndone. To help with writing tests that need to check for events, and expect\nspecific states, the Move CLI also has a built-in expected-value testing\nframework. Each test is run independently in its own sandbox so state does not\npersist from one test to another.\n\nEach test is structured as a Move package along with an additional `args.txt` file that\nspecifies a sequence of Move CLI commands that should be run in that\ndirectory.\nAdditionally, there must be an `args.exp` file that contain the expected\noutput from running the sequence of Move CLI commands specified in the\n`args.txt` file for that test.\n\nFor example, if we wanted to create a Move CLI test that reran all of the\ncommands that we've seen so far, we could do so by adding an `args.txt`\nto the `readme` directory that we created at the start and that we've been\nadding scripts and modules to:\n\n```\nreadme/\n├── args.txt\n├── Move.toml\n└── sources\n ├── debug_script.move\n ├── Test.move\n └── test_script.move\n```\n\nAnd, where the `args.txt` file contains the following Move CLI commands:\n\n```shell\n$ cd ..\n$ cat readme/args.txt\n## Arg files can have comments!\nsandbox run sources/debug_script.move --signers 0xf\nsandbox run sources/debug_script.move --signers 0xf\nbuild\nsandbox publish\nsandbox view storage/0x00000000000000000000000000000002/modules/Test.mv\nsandbox run sources/test_script.move --signers 0xf -v\nsandbox view storage/0x0000000000000000000000000000000f/resources/0x00000000000000000000000000000002::Test::Resource.bcs\n```\n\nWe can then use the `move sandbox test` command and point it at the `readme` directory to run each of these\nMove CLI commands for us in sequence:\n\n```shell\n$ move sandbox exp-test -p readme\n...\n0 / 1 test(s) passed.\nError: 1 / 1 test(s) failed.\n```\n\nHowever, as we see this test will fail since there is no `args.exp` file for the test\nyet. We can generate this expectation file by setting the `UPDATE_BASELINE`\nenvironment variable when running the test:\n\n```shell\n$ UPDATE_BASELINE=1 move sandbox exp-test -p readme\n1 / 1 test(s) passed.\n```\n\nThere should now be an `args.exp` file under the `readme` directory that\ncontains the expected output of running the sequence of Move CLI commands\nin the `args.txt` file:\n\n```shell\n$ cat readme/args.exp\nCommand `sandbox run sources/debug_script.move --signers 0xf`:\n[debug] (&) { 0000000000000000000000000000000f }\nCommand `sandbox run sources/debug_script.move --signers 0xf --mode bare`:\n...\n```\n\n#### Testing with code coverage tracking\n\nCode coverage has been an important metric in software testing. In Move CLI expected value tests, we\naddress the need for code coverage information with an additional flag,\n`--track-cov`, that can be passed to the `move sandbox exp-test` command.\n\nNote: To view coverage information, the Move CLI must be installed with the `--debug` flag;\ni.e., `cargo install --debug --path move/language/tools/move-cli`.\n\nUsing our running example to illustrate:\n```shell\n$ move sandbox exp-test -p readme --track-cov\n1 / 1 test(s) passed.\nModule 00000000000000000000000000000002::Test\n fun publish\n total: 5\n covered: 5\n % coverage: 100.00\n fun unpublish\n total: 6\n covered: 0\n % coverage: 0.00\n fun write\n total: 7\n covered: 0\n % coverage: 0.00\n>>> % Module coverage: 27.78\n```\n\nThe output indicates that not only the test is passed, but also that 100%\ninstruction coverage is observed in the `publish` funciton. This is expected\nas the whole purpose of our `test_script.move` is to run the `publish` function.\nAt the same time, the other two functions, `unpublish` and `write`, are never\nexecuted, making the average coverage 27.78% for the whole `Test` module.\n\nInternally, Move CLI uses the tracing feature provided by the Move VM to record\nwhich instructions in the compiled bytecode are executed and uses this\ninformation to calculate code coverage. Instruction coverage in Move can\nusually serve the purpose of line coverage in common C/C++/Rust coverage\ntracking tools.\n\nNote that the coverage information is aggregated across multiple `run` commands\nin `args.txt`. To illustrate this, suppose that we have another test script,\n`test_unpublish_script.move`, under `readme/sources` with the following\ncontent:\n\n```rust\nscript {\nuse 0x2::Test;\nfun test_unpublish_script(account: signer) {\n Test::unpublish(&account)\n}\n}\n```\n\nWe further add a new command to the end of `args.txt`\n(`args.exp` needs to be updated too).\n```shell\nsandbox run sources/test_unpublish_script.move --signers 0xf -v\n```\n\nNow we can re-test the `readme` again\n```shell\n$ move sandbox exp-test -p readme --track-cov\n1 / 1 test(s) passed.\nModule 00000000000000000000000000000002::Test\n fun publish\n total: 5\n covered: 5\n % coverage: 100.00\n fun unpublish\n total: 6\n covered: 6\n % coverage: 100.00\n fun write\n total: 7\n covered: 0\n % coverage: 0.00\n>>> % Module coverage: 61.11\n```\n\nThis time, note that the `unpublish` function is 100% covered too and the\noverall module coverage is boosted to 61.11%.\n\n### Detecting breaking changes\n\nThe `move sandbox publish` command automatically detects when upgrading a module may lead to a breaking change.\nThere are two kinds of breaking changes:\n\n* Linking compatibility (e.g., removing or changing the signature of a public function that is invoked by other modules, removing a\nstruct or resource type used by other modules)\n* Layout compatibility (e.g., adding/removing a resource or struct field)\n\nThe breaking changes analysis performed by `move sandbox publish` is necessarily conservative. For example, say we `move sandbox publish` the following\nmodule:\n\n```\naddress 0x2 {\nmodule M {\n struct S has key { f: u64, g: u64 }\n}\n}\n```\n\nand then wish to upgrade it to the following:\n\n```\naddress 0x2 {\nmodule M {\n struct S has key { f: u64 }\n}\n}\n```\n\nRunning `move sandbox publish` on this new version will fail:\n\n```\nBreaking change detected--publishing aborted. Re-run with --ignore-breaking-changes to publish anyway.\nError: Layout API for structs of module 00000000000000000000000000000002::M has changed. Need to do a data migration of published structs\n```\n\nIn this case, we know we have not published any instances of `S` in global storage, so it is safe to re-run `move sandbox publish --ignore-breaking-changes` (as recommended).\nWe can double-check that this was not a breaking change by running `move sandbox doctor`.\nThis handy command runs exhaustive sanity checks on global storage to detect any breaking changes that occurred in the past:\n* All modules pass the bytecode verifier\n* All modules link against their dependencies\n* All resources deserialize according to their declared types\n* All events deserialize according to their declared types\n","third_party/move/tools/move-unit-test/README.md":"---\nid: move-unit-test\ntitle: Move Unit Testing Framework\ncustom_edit_url: https://github.com/move-language/move/edit/main/language/tools/move-unit-test/README.md\n---\n\n# Summary\n\nThis crate defines the core logic for running and reporting Move unit\ntests. Move unit testing is made up of two main components; a test runner,\nand a test reporter.\n\nIt's important to also note here that unit tests can be run using the\n[stackless bytecode interpreter](../../move-prover/interpreter). If the\nunit tests are run with the stackless bytecode interpreter and the test\nreturns a value, then the result of executing the unit test with the Move\nVM and the result of the interpreter will be compared and an error will\nbe raised if they are not equal.\n\nDetailed information on how to use unit tests as a user of Move can be\nfound [here](https://move-language.github.io/move/unit-testing.html).\n\n## Test Runner\n\nThe test runner consumes a\n[`TestPlan`](../../move-compiler/src/unit_test/mod.rs): this is a\ndatastructure that is built by the Move compiler, based on source `#[test]`\nattributes. At a high level, this test plan consists of:\n1. A list of `ModuleTestPlan`s for each non-dependency module. A\n `ModuleTestPlan` consists of a list of unit tests declared in a module,\n along with its arguments and whether the unit test is an expected\n failure or not.\n2. Compiled modules for each source module, along with compiled modules for\n all transitive dependencies.\n3. The source text and source maps for every source and transitive dependency.\n\nThe test runner takes this `TestPlan` along with various configuration\noptions (e.g., number of threads). From this information the test runner\ncreates an initial test state consisting solely of the modules in bullet\n(2) above. This will be the same initial state for all unit tests.\n\nAfter constructing this initial state, a work queue of `ModuleTestPlan`s is\npassed to a [`rayon`](https://docs.rs/rayon/latest/rayon/) threadpool to\nexecute. After the execution of each test a `PASS`, `FAIL` or `TIMEOUT` is\nreported to the writer (usually `std::io::stdout`) as soon as the test's\nresult is known. The result of running tests in a `ModuleTestPlan` is a\nmapping of failing and passing tests (where failing means that the tests\nfailed when it was expected to fail, or vis versa) along with profiling\ninformation and failure information if applicable. These test statistics\nfor each module are combined in parallel and produce a `TestResults` data\nstructure.\n\n## Test Reporter\n\nAfter all of the unit tests have been run and a `TestResults` data\nstructure has been created, the test reporter will iterate through the test\nresults, and will use the data in the `TestFailure` info along with the\nsource maps and source text in the test plan to display source-level error\nmessages for any failing tests.\n\nDepending on the options passed to the unit testing framework, additional\ninfo, such as the global storage state at the point of error for each\nfailing test, or the execution time and number of instructions for each\ntest may be display at the end of a test run.\n","third_party/move/move-examples/diem-framework/move-packages/core/README.md":"This folder contains a Move package consisting of core Move modules defining functionalities needed by\nany Diem-based blockchains. To start your own Diem-based blockchain, you can create a Move package that\ndepends on this core package and write your own wrapper modules for the account module as well as the\non-chain configuration modules. [`experimental` folder](../experimental) provides an example of such\nMove package.\n\nNext we briefly describe how to write the wrapper modules and how Move's powerful type system can provide flexibility\nas well as safety for your chain.\n\nYou will need to write wrapper modules for the following core modules:\n- Account\n- CoreGenesis\n- DiemConsensusConfig\n- DiemSystem\n- DiemVersion\n- DiemVMConfig\n- ParallelExecutionConfig\n- ValidatorConfig\n- ValidatorOperatorConfig\n\n\nEvery module in this list contains the following resources and functions:\n- A chain marker resource with a `phantom T` type parameter\n- An initialization function that has to be called during chain-specific genesis and publishes a chain marker resource under\n `@CoreResources` address as well as any relevant configuration resources\n- At least one setter function that requires a `Cap` as parameter and modifies the configuration resource(s).\n And at the beginning of the function we check the existence of the chain marker resource.\n\n#### Why is the chain marker resource needed?\n\nWe want to provide the safety guarantee that only the authorized wrapper module can define access\ncontrol policies for the resources. Therefore, we need to make sure that only the wrapper module can call the public\nsetter functions. However, we are designing for wrapper modules that don't even exist right now, so we have to somehow\n\"register\" the wrapper module at the chain-specific genesis. The solution to this question is the chain marker resource.\nThis resource has a phantom type parameter that should be instantiated with a type owned by the wrapper module such as\n`ExperimentalVersion` resource. Each setter function requires a capability parameter instantiated with this type. Since\nthe acquisition of this capability requires a value of this witness type and this type is owned by the wrapper module,\nwe know for sure that only the wrapper module can decide who or which module is allowed to modify the configurations.\n\n#### How to write wrapper modules?\n\nRead `DiemVersion.move` and then `ExperimentalVersion.move` to get the idea.\n","aptos-move/move-examples/large_packages/README.md":"# Moved to https://aptos-labs.github.io/framework-book/aptos-experimental/large_packages.html\n"},"items":[{"name":"README.md","path":"aptos-move/move-examples/large_packages/README.md","rawUrl":"https://raw.githubusercontent.com/aptos-labs/aptos-core/HEAD/aptos-move/move-examples/large_packages/README.md","title":"large_packages Documentation","category":"plugin-manifest","format":"markdown","content":"# Moved to https://aptos-labs.github.io/framework-book/aptos-experimental/large_packages.html\n","isInternal":false,"tokens":22,"sizeBytes":94},{"name":"README.md","path":"third_party/move/extensions/move-table-extension/README.md","rawUrl":"https://raw.githubusercontent.com/aptos-labs/aptos-core/HEAD/third_party/move/extensions/move-table-extension/README.md","title":"move-table-extension Documentation","category":"plugin-manifest","format":"markdown","content":"This crate contains an extension to the Move language with large-scale storage tables.\n\nIn order to use this extension with the Move CLI and package system, you need to compile with\n`feature = [\"table-extension\"]`.\n\nIn order to use this extension in your adapter, you do something as follows:\n\n```rust\nuse move_core_types::account_address::AccountAddress;\nuse move_stdlib::natives;\nuse move_table_extension::NativeTableContext;\nuse move_vm_runtime::move_vm::MoveVM;\nuse move_vm_runtime::native_functions::NativeContextExtensions;\n\nfn run() {\n let resource_resolver = unimplemented!(); // a resource resolver the adapter provides\n let txn_hash = unimplemented!(); // a unique hash for table creation for this transaction\n let table_resolver = unimplemented!(); // a remote table resolver the adapter provides\n let std_addr = unimplemented!(); // address where to deploy the std lib\n let extension_addr = unimplemented!(); // address where to deploy the table extension\n\n let mut extensions = NativeContextExtensions::default();\n extensions.add(NativeTableContext::new(txn_hash, table_resolver));\n let mut natives = move_stdlib::natives::all_natives(std_addr);\n natives.append(&mut move_table_extension::table_natives(extension_addr));\n let vm = MoveVM::new(natives);\n\n let session = vm.new_session_with_extensions(resource_resolver, extensions);\n let result = session.execute_function(..)?;\n let (change_set, events, extensions) = session.finish_with_extensions()?;\n let table_change_set = extensions.get::().into_change_set();\n\n // Do something with the table change set\n // ...\n}\n```\n","isInternal":false,"tokens":351,"sizeBytes":1653},{"name":"README.md","path":"third_party/move/extensions/README.md","rawUrl":"https://raw.githubusercontent.com/aptos-labs/aptos-core/HEAD/third_party/move/extensions/README.md","title":"extensions Documentation","category":"plugin-manifest","format":"markdown","content":"This tree contains extensions to the Move core language and runtime. Those extensions are not enabled by\ndefault but can be integrated into a Move-based environment following the instructions found for each individual\nextension.\n\nSome extensions may eventually become part of the core language after some period of stabilization.\n","isInternal":false,"tokens":55,"sizeBytes":330},{"name":"README.md","path":"third_party/move/move-examples/diem-framework/move-packages/core/README.md","rawUrl":"https://raw.githubusercontent.com/aptos-labs/aptos-core/HEAD/third_party/move/move-examples/diem-framework/move-packages/core/README.md","title":"core Documentation","category":"plugin-manifest","format":"markdown","content":"This folder contains a Move package consisting of core Move modules defining functionalities needed by\nany Diem-based blockchains. To start your own Diem-based blockchain, you can create a Move package that\ndepends on this core package and write your own wrapper modules for the account module as well as the\non-chain configuration modules. [`experimental` folder](../experimental) provides an example of such\nMove package.\n\nNext we briefly describe how to write the wrapper modules and how Move's powerful type system can provide flexibility\nas well as safety for your chain.\n\nYou will need to write wrapper modules for the following core modules:\n- Account\n- CoreGenesis\n- DiemConsensusConfig\n- DiemSystem\n- DiemVersion\n- DiemVMConfig\n- ParallelExecutionConfig\n- ValidatorConfig\n- ValidatorOperatorConfig\n\n\nEvery module in this list contains the following resources and functions:\n- A chain marker resource with a `phantom T` type parameter\n- An initialization function that has to be called during chain-specific genesis and publishes a chain marker resource under\n `@CoreResources` address as well as any relevant configuration resources\n- At least one setter function that requires a `Cap` as parameter and modifies the configuration resource(s).\n And at the beginning of the function we check the existence of the chain marker resource.\n\n#### Why is the chain marker resource needed?\n\nWe want to provide the safety guarantee that only the authorized wrapper module can define access\ncontrol policies for the resources. Therefore, we need to make sure that only the wrapper module can call the public\nsetter functions. However, we are designing for wrapper modules that don't even exist right now, so we have to somehow\n\"register\" the wrapper module at the chain-specific genesis. The solution to this question is the chain marker resource.\nThis resource has a phantom type parameter that should be instantiated with a type owned by the wrapper module such as\n`ExperimentalVersion` resource. Each setter function requires a capability parameter instantiated with this type. Since\nthe acquisition of this capability requires a value of this witness type and this type is owned by the wrapper module,\nwe know for sure that only the wrapper module can decide who or which module is allowed to modify the configurations.\n\n#### How to write wrapper modules?\n\nRead `DiemVersion.move` and then `ExperimentalVersion.move` to get the idea.\n","isInternal":false,"tokens":480,"sizeBytes":2441},{"name":"README.md","path":"third_party/move/tools/move-cli/README.md","rawUrl":"https://raw.githubusercontent.com/aptos-labs/aptos-core/HEAD/third_party/move/tools/move-cli/README.md","title":"move-cli Documentation","category":"plugin-manifest","format":"markdown","content":"# Move CLI\n\nThe Move command-line interface (Move CLI) is a tool that provides an easy way to interact with Move, to experiment\nwith writing and running Move code, and to experiment with developing new tools useful\nfor Move development. To reflect this, the Move CLI commands are grouped into\nthree main subcommands:\n* **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.\n* **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.\n* **experimental commands**: are experimental commands that are currently in development.\n\nEvery Move CLI command, with the exception of `package create`, is expected to be run within the context of a [Move package](https://move-language.github.io/move/packages.html).\n\n## Installation\n```shell\n$ cargo install --path move/language/tools/move-cli\n```\nor\n```shell\n$ cargo install --git https://github.com/move-language/move move-cli --branch main\n```\n\nThis will install the `move` binary in your Cargo binary directory. On\nmacOS and Linux this is usually `~/.cargo/bin`. You'll want to make sure\nthis location is in your `PATH` environment variable.\n\nNow you should be able to run the Move CLI:\n\n```shell\n$ move\nMove 0.1.0\nCLI frontend for Move compiler and VM\n\nUSAGE:\n move [FLAGS] [OPTIONS] \n ...\n```\n\nWe'll go through the most common Move CLI commands and flags here, however\nyou can find the complete list of commands available by calling `move\n--help`. Additionally, the complete list of flags and options available\nfor each Move CLI command can be found by passing the `--help` flag to it,\ni.e., `move --help`.\n\n## Package Commands\n\nPackage commands provide wrappers with sane defaults around other commands\nthat are provided either by various Move tools, compiler, or prover.\n\nThe `move new` command will create a new empty Move package:\n```shell\n$ move new # Create a Move package under the current dir\n$ move new -p # Create a Move package under path \n```\n\nFrom within a package's root directory, you can build the modules and/or scripts that you have written in the package with:\n```shell\n$ move build # Builds the Move package you are currently in\n$ move build -p # Builds the Move package at \n```\n\nThe compiled artifacts will by default be stored in the `build` directory. You\ncan change where the build artifacts are saved by passing the optional `--build-dir` flag:\n\n```shell\n$ move build --build-dir # Build current Move package and save artifacts under \n```\n\nYou can verify the specifications in a Move package using the Move Prover with the `prove` command:\n\n```shell\n$ move prove # Verify the specifications in the current package\n$ move prove -p # Verify the specifications in the package at \n```\n\nIn order to run the Move Prover [additional tools need to be\ninstalled](https://github.com/move-language/move/blob/main/language/move-prover/doc/user/install.md).\nInformation on the Move Prover and its configuration options can be found\n[here](https://github.com/move-language/move/blob/main/language/move-prover/doc/user/prover-guide.md)\nand\n[here](https://github.com/move-language/move/blob/main/language/move-prover/doc/user/spec-lang.md).\n\nYou can also run unit tests in a package using the `test` command\n\n```shell\n$ move test # Run Move unit tests in the current package\n$ move test -p # Run Move unit tests in the package at \n```\n## Sandbox Commands\n\nThe sandbox allows you to experiment with writing and running Move code without\nvalidators, a blockchain, or transactions. Persistent data is stored on-disk in\na directory structure that mimics the Move memory model\n\n### Project structure\n\nEach sandbox command is run in the context of a Move package. So let's create a\nMove package that we'll use for the code in this README and `cd` into it:\n\n```shell\n$ move new readme\n$ cd readme\n```\n\n### Compiling and running scripts\n\nLet's first start out with a simple script that prints its [`signer`](https://move-language.github.io/move/signer.html).\nCreate a file named `sources/debug_script.move` and type the following into it:\n\n```rust\n// sources/debug_script.move\nscript {\nuse std::debug;\nfun debug_script(account: signer) {\n debug::print(&account)\n}\n}\n```\n\nBefore we can run this however, we need to import the Move standard library\nnursery in order to have access to the `Debug` module and `Std` [named\naddress](https://move-language.github.io/move/address.html#named-addresses).\nYou can specify dependencies locally, or using a Git URL. Here, we will specify\nit using Git, so add the following to the `Move.toml` file in the `readme`\ndirectory:\n\n```toml\n[addresses]\nstd = \"0x1\" # Specify and assign 0x1 to the named address \"std\"\n\n[dependencies]\nMoveNursery = { git = \"https://github.com/move-language/move.git\", subdir = \"language/move-stdlib/nursery\", rev = \"main\" }\n# ^ ^ ^ ^\n# Git dependency Git clone URL Subdir under git repo (optional) Git revision to use\n```\n\nNow let's try running the script -- the very first time may take some time since the package command will clone the repository at the given URL, but subsequent calls should be fast:\n\n```shell\n$ move sandbox run sources/debug_script.move --signers 0xf\n[debug] (&) { 0000000000000000000000000000000f }\n```\n\nThe `--signers 0xf` argument indicates which account address(es) have signed\noff on the script. Omitting `--signers` or passing multiple signers to this\nsingle-`signer` script will trigger a type error.\n\n### Passing arguments\n\nThe CLI supports passing non-`signer` arguments to `move sandbox run` via `--args`. The following argument types are supported:\n* `bool` literals (`true`, `false`)\n* `u64` literals (e.g., `10`, `58`)\n* `address` literals (e.g., `0x12`, `0x0000000000000000000000000000000f`)\n* hexadecimal strings (e.g., `'x\"0012\"'` will parse as the `vector` value `[00, 12]`)\n* ASCII strings (e.g., `'b\"hi\"'` will parse as the `vector` value `[68, 69]`)\n\n### Publishing new modules\n\nWhen executing a transaction script you'll often want to call into different\nMove modules, like in the example above with the `Debug` module. New modules can\nbe added to the `sources` directory in the package where the CLI is being\ninvoked. You can also add dependencies on other packages to have access to the\nmodules that they define (just like we did with the `Debug` module above). The\n`move sandbox run` command will compile and publish each module in the package, and\nin each of the package's transitive dependencies, before running the given script.\n\nTry saving this code in `sources/Test.move`:\n\n```rust\n// sources/Test.move\nmodule 0x2::Test {\n use std::signer;\n\n struct Resource has key { i: u64 }\n\n public fun publish(account: &signer) {\n move_to(account, Resource { i: 10 })\n }\n\n public fun write(account: &signer, i: u64) acquires Resource {\n borrow_global_mut(signer::address_of(account)).i = i;\n }\n\n public fun unpublish(account: &signer) acquires Resource {\n let Resource { i: _ } = move_from(signer::address_of(account));\n }\n}\n```\n\nNow, try\n\n```shell\n$ move build\n```\n\nThis will cause the CLI to compile and typecheck the modules under\n`sources`, but it won't publish the module bytecode under `storage`. You can\ncompile and publish the module by running the `move sandbox publish` command\n(here we pass the `-v` or verbose flag to get a better understanding of what's\nhappening):\n\n```shell\n$ move sandbox publish -v\nFound 1 modules\nPublishing a new module 00000000000000000000000000000002::Test (wrote 253 bytes)\nWrote 253 bytes of module ID's and code\n```\n\nNow, if we take a look under `storage`, we will see the published bytecode\nfor our `Test` module:\n\n```shell\n$ ls storage/0x00000000000000000000000000000002/modules\nTest.mv\n```\n\nWe can also inspect the compiled bytecode in storage using `move sandbox view`:\n\n```shell\n$ move sandbox view storage/0x00000000000000000000000000000002/modules/Test.mv\nmodule 2.Test {\nstruct Resource has key {\n i: u64\n}\n\npublic publish() {\n 0: MoveLoc[0](Arg0: &signer)\n 1: LdU64(10)\n 2: Pack[0](Resource)\n 3: MoveTo[0](Resource)\n 4: Ret\n}\npublic unpublish() {\n 0: MoveLoc[0](Arg0: &signer)\n 1: Call[3](address_of(&signer): address)\n 2: MoveFrom[0](Resource)\n 3: Unpack[0](Resource)\n 4: Pop\n 5: Ret\n}\npublic write() {\n 0: CopyLoc[1](Arg1: u64)\n 1: MoveLoc[0](Arg0: &signer)\n 2: Call[3](address_of(&signer): address)\n 3: MutBorrowGlobal[0](Resource)\n 4: MutBorrowField[0](Resource.i: u64)\n 5: WriteRef\n 6: Ret\n}\n}\n```\n\nYou can also look at the compiled bytecode before publishing to `storage` by\nrunning either `move disassemble --name ` or `move\ndisassemble --name --interactive` to interactively inspect the\nbytecode and how it relates to the Move source code:\n\n```shell\n$ move disassemble --name Test --interactive # You can quit by pressing \"q\"\n$ move disassemble --name Test\n// Move bytecode v4\nmodule 2.Test {\nstruct Resource has key {\n i: u64\n}\n\npublic publish() {\nB0:\n 0: MoveLoc[0](account: &signer)\n 1: LdU64(10)\n 2: Pack[0](Resource)\n 3: MoveTo[0](Resource)\n 4: Ret\n}\npublic unpublish() {\nB0:\n 0: MoveLoc[0](account: &signer)\n 1: Call[3](address_of(&signer): address)\n 2: MoveFrom[0](Resource)\n 3: Unpack[0](Resource)\n 4: Pop\n 5: Ret\n}\npublic write() {\nB0:\n 0: CopyLoc[1](i: u64)\n 1: MoveLoc[0](account: &signer)\n 2: Call[3](address_of(&signer): address)\n 3: MutBorrowGlobal[0](Resource)\n 4: MutBorrowField[0](Resource.i: u64)\n 5: WriteRef\n 6: Ret\n}\n}\n```\n\n### Updating state\n\nLet's exercise our new `Test` module by running the following script:\n\n```rust\n// sources/test_script.move\nscript {\nuse 0x2::Test;\nfun test_script(account: signer) {\n Test::publish(&account)\n}\n}\n```\n\nThis script invokes the `publish` function of our `Test` module, which will\npublish a resource of type `Test::Resource` under the signer's account.\nLet's first see what this script will change without committing those\nchanges first. We can do this by passing the `--dry-run` flag:\n\n```shell\n$ move sandbox run sources/test_script.move --signers 0xf -v --dry-run\nCompiling transaction script...\nChanged resource(s) under 1 address(es):\n Changed 1 resource(s) under address 0000000000000000000000000000000f:\n Added type 0x2::Test::Resource: [10, 0, 0, 0, 0, 0, 0, 0] (wrote 40 bytes)\nWrote 40 bytes of resource ID's and data\n key 0x2::Test::Resource {\n i: 10\n }\nDiscarding changes; re-run without --dry-run if you would like to keep them.\n```\n\nEverything looks good, so we can run this again, but this time commit the\nchanges by removing the `--dry-run` flag:\n\n```shell\n$ move sandbox run sources/test_script.move --signers 0xf -v\nCompiling transaction script...\nChanged resource(s) under 1 address(es):\n Changed 1 resource(s) under address 0000000000000000000000000000000f:\n Added type 0x2::Test::Resource: [10, 0, 0, 0, 0, 0, 0, 0] (wrote 40 bytes)\nWrote 40 bytes of resource ID's and data\n key 0x2::Test::Resource {\n i: 10\n }\n```\n\nWhile the verbose flag used above (`-v`) shows resource changes, it is also\npossible to view them manually.\nWe can inspect the newly published resource using `move sandbox view` since\nthe change has been committed:\n\n```shell\n$ move sandbox view storage/0x0000000000000000000000000000000f/resources/0x00000000000000000000000000000002::Test::Resource.bcs\nkey 0x2::Test::Resource {\n i: 10\n}\n```\n\n#### Cleaning state\n\nSince state persists from one call to the Move CLI to another, there will\nfrequently be times where you want to start again at a clean state. This\ncan be done using the `move sandbox clean` command which will remove the\n`storage` and `build` directories:\n\n```shell\n$ move sandbox view storage/0x0000000000000000000000000000000f/resources/0x00000000000000000000000000000002::Test::Resource.bcs\nresource 0x2::Test::Resource {\n i: 10\n}\n$ move sandbox clean\n$ move sandbox view storage/0x0000000000000000000000000000000f/resources/0x00000000000000000000000000000002::Test::Resource.bcs\nError: `move sandbox view ` must point to a valid file under storage\n```\n\n### Expected Value Testing with the Move CLI\n\nAs mentioned previously, Move has a unit testing framework. However, unit tests\ncannot test everything -- in particular testing for events cannot be easily\ndone. To help with writing tests that need to check for events, and expect\nspecific states, the Move CLI also has a built-in expected-value testing\nframework. Each test is run independently in its own sandbox so state does not\npersist from one test to another.\n\nEach test is structured as a Move package along with an additional `args.txt` file that\nspecifies a sequence of Move CLI commands that should be run in that\ndirectory.\nAdditionally, there must be an `args.exp` file that contain the expected\noutput from running the sequence of Move CLI commands specified in the\n`args.txt` file for that test.\n\nFor example, if we wanted to create a Move CLI test that reran all of the\ncommands that we've seen so far, we could do so by adding an `args.txt`\nto the `readme` directory that we created at the start and that we've been\nadding scripts and modules to:\n\n```\nreadme/\n├── args.txt\n├── Move.toml\n└── sources\n ├── debug_script.move\n ├── Test.move\n └── test_script.move\n```\n\nAnd, where the `args.txt` file contains the following Move CLI commands:\n\n```shell\n$ cd ..\n$ cat readme/args.txt\n## Arg files can have comments!\nsandbox run sources/debug_script.move --signers 0xf\nsandbox run sources/debug_script.move --signers 0xf\nbuild\nsandbox publish\nsandbox view storage/0x00000000000000000000000000000002/modules/Test.mv\nsandbox run sources/test_script.move --signers 0xf -v\nsandbox view storage/0x0000000000000000000000000000000f/resources/0x00000000000000000000000000000002::Test::Resource.bcs\n```\n\nWe can then use the `move sandbox test` command and point it at the `readme` directory to run each of these\nMove CLI commands for us in sequence:\n\n```shell\n$ move sandbox exp-test -p readme\n...\n0 / 1 test(s) passed.\nError: 1 / 1 test(s) failed.\n```\n\nHowever, as we see this test will fail since there is no `args.exp` file for the test\nyet. We can generate this expectation file by setting the `UPDATE_BASELINE`\nenvironment variable when running the test:\n\n```shell\n$ UPDATE_BASELINE=1 move sandbox exp-test -p readme\n1 / 1 test(s) passed.\n```\n\nThere should now be an `args.exp` file under the `readme` directory that\ncontains the expected output of running the sequence of Move CLI commands\nin the `args.txt` file:\n\n```shell\n$ cat readme/args.exp\nCommand `sandbox run sources/debug_script.move --signers 0xf`:\n[debug] (&) { 0000000000000000000000000000000f }\nCommand `sandbox run sources/debug_script.move --signers 0xf --mode bare`:\n...\n```\n\n#### Testing with code coverage tracking\n\nCode coverage has been an important metric in software testing. In Move CLI expected value tests, we\naddress the need for code coverage information with an additional flag,\n`--track-cov`, that can be passed to the `move sandbox exp-test` command.\n\nNote: To view coverage information, the Move CLI must be installed with the `--debug` flag;\ni.e., `cargo install --debug --path move/language/tools/move-cli`.\n\nUsing our running example to illustrate:\n```shell\n$ move sandbox exp-test -p readme --track-cov\n1 / 1 test(s) passed.\nModule 00000000000000000000000000000002::Test\n fun publish\n total: 5\n covered: 5\n % coverage: 100.00\n fun unpublish\n total: 6\n covered: 0\n % coverage: 0.00\n fun write\n total: 7\n covered: 0\n % coverage: 0.00\n>>> % Module coverage: 27.78\n```\n\nThe output indicates that not only the test is passed, but also that 100%\ninstruction coverage is observed in the `publish` funciton. This is expected\nas the whole purpose of our `test_script.move` is to run the `publish` function.\nAt the same time, the other two functions, `unpublish` and `write`, are never\nexecuted, making the average coverage 27.78% for the whole `Test` module.\n\nInternally, Move CLI uses the tracing feature provided by the Move VM to record\nwhich instructions in the compiled bytecode are executed and uses this\ninformation to calculate code coverage. Instruction coverage in Move can\nusually serve the purpose of line coverage in common C/C++/Rust coverage\ntracking tools.\n\nNote that the coverage information is aggregated across multiple `run` commands\nin `args.txt`. To illustrate this, suppose that we have another test script,\n`test_unpublish_script.move`, under `readme/sources` with the following\ncontent:\n\n```rust\nscript {\nuse 0x2::Test;\nfun test_unpublish_script(account: signer) {\n Test::unpublish(&account)\n}\n}\n```\n\nWe further add a new command to the end of `args.txt`\n(`args.exp` needs to be updated too).\n```shell\nsandbox run sources/test_unpublish_script.move --signers 0xf -v\n```\n\nNow we can re-test the `readme` again\n```shell\n$ move sandbox exp-test -p readme --track-cov\n1 / 1 test(s) passed.\nModule 00000000000000000000000000000002::Test\n fun publish\n total: 5\n covered: 5\n % coverage: 100.00\n fun unpublish\n total: 6\n covered: 6\n % coverage: 100.00\n fun write\n total: 7\n covered: 0\n % coverage: 0.00\n>>> % Module coverage: 61.11\n```\n\nThis time, note that the `unpublish` function is 100% covered too and the\noverall module coverage is boosted to 61.11%.\n\n### Detecting breaking changes\n\nThe `move sandbox publish` command automatically detects when upgrading a module may lead to a breaking change.\nThere are two kinds of breaking changes:\n\n* Linking compatibility (e.g., removing or changing the signature of a public function that is invoked by other modules, removing a\nstruct or resource type used by other modules)\n* Layout compatibility (e.g., adding/removing a resource or struct field)\n\nThe breaking changes analysis performed by `move sandbox publish` is necessarily conservative. For example, say we `move sandbox publish` the following\nmodule:\n\n```\naddress 0x2 {\nmodule M {\n struct S has key { f: u64, g: u64 }\n}\n}\n```\n\nand then wish to upgrade it to the following:\n\n```\naddress 0x2 {\nmodule M {\n struct S has key { f: u64 }\n}\n}\n```\n\nRunning `move sandbox publish` on this new version will fail:\n\n```\nBreaking change detected--publishing aborted. Re-run with --ignore-breaking-changes to publish anyway.\nError: Layout API for structs of module 00000000000000000000000000000002::M has changed. Need to do a data migration of published structs\n```\n\nIn this case, we know we have not published any instances of `S` in global storage, so it is safe to re-run `move sandbox publish --ignore-breaking-changes` (as recommended).\nWe can double-check that this was not a breaking change by running `move sandbox doctor`.\nThis handy command runs exhaustive sanity checks on global storage to detect any breaking changes that occurred in the past:\n* All modules pass the bytecode verifier\n* All modules link against their dependencies\n* All resources deserialize according to their declared types\n* All events deserialize according to their declared types\n","isInternal":false,"tokens":5105,"sizeBytes":19927},{"name":"README.md","path":"third_party/move/tools/move-package/README.md","rawUrl":"https://raw.githubusercontent.com/aptos-labs/aptos-core/HEAD/third_party/move/tools/move-package/README.md","title":"move-package Documentation","category":"plugin-manifest","format":"markdown","content":"---\nid: move-package\ntitle: Move Package\ncustom_edit_url: https://github.com/move-language/move/edit/main/language/tools/move-package/README.md\n---\n\n# Summary\n\nThe Move package crate contains the logic for parsing, resolving, and\nbuilding Move packages. It is meant to be used as a library, both for\nbuilding packages (e.g., by the Move CLI), or by other applications that\nmay be working with Move packages. The package system is split into three\nmain phases: parsing, resolution, and compilation.\n\n## Parsing and Manifest Layout\n\nThe parsing and manifest layout logic is defined in the\n[`./src/source_package`](./src/source_package) directory. This defines the\nlayout and the set of required and optional directories for a Move package\nin [`./src/source_package/layout.rs`](./src/source_package/layout.rs), it\ndefines the format of the parsed Move package manifest (\"`Move.toml`\") in\n[`./src/source_package/parsed_manifest.rs`](./src/source_package/parsed_manifest.rs),\nand it defines the parser for the Move package manifest in\n[`./src/source_package/manifest_parser.rs`](./src/source_package/manifest_parser.rs).\nNote that we don't have a tokenizer/lexer as we use the TOML lexer. This\nalso resolves git dependencies to where they will live on the local file\nsystem (but does not clone them).\n\n## Resolution\n\nThe resolution phase is responsible for resolving all packages and building\nthe package graph which represents the dependency relations between\npackages. It is also responsible for ensuring that all named addresses have\na value assigned to them, and that there are no conflicting assignments.\nThe package graph is rooted at the package being built and is a DAG.\n\nWhen building the package graph we do the following conceptual operations:\nverify that dependencies exist at the declared locations, that their\npackage names and source digests match (if applicable), clone git\ndependencies if they don't already exist locally, build a dependency graph\nof Move packages and ensure this forms a DAG, compute an\nassignment for each named address in each Move package in the package\ngraph, and ensure that the resulting named address assignment is valid.\n\nAll of the above steps are fairly straightforward, with the possible\nexception of named addresses: each package will have a set of in-scope\nnamed addresses. The set of in-scope named addresses for a package `P` is\ndefined as the transitive closure of all named addresses in the\ndependencies of `P`. Additionally, a package can rename named addresses\nthat are in-scope as long as the final assignment of a value to the set of\nnamed addresses can be unified. To ensure that named addresses are\nunifiable across renamings, resolution performs unification across named\naddresses using a `Rc>>`: when a named address first\nenters scope in the package graph a `Rc>` is created for it.\nThis refcell is then shared to all uses of the named address _even across\nrenamings_ and when a value is assigned to it, the value must (1) match the\ncurrent value contained within the `Option`, or (2) the `Option` is `None`,\nand the value is placed into the refcell.\n\n## Compilation\n\nThe final stage of the package system is compilation. All logic relating to\nthe final build artifacts, or global environment creation, is contained in\nthe [`./src/compilation`](./src/compilation) directory. The package layout\nfor compiled Move packages is defined in\n[`./src/compilation/package_layout.rs`](./src/compilation/package_layout.rs).\n\nThe [`./src/compilation/build_plan.rs`](./src/compilation/build_plan.rs)\ncontains the logic for driving the compilation of a package and the\ncompilation of all of the package's dependencies given a valid resolution\ngraph. The logic in\n[`./src/compilation/compiled_package.rs`](./src/compilation/compiled_package.rs)\ncontains the definition of the in-memory representation of compiled Move\npackages and other data structures and APIs relating to compiled Move\npackages, along with the logic for compiling a _single_ Move package\nassuming all of its dependencies are already compiled and saved to disk.\nThis is driven by the logic in\n[`./src/compilation/build_plan.rs`](./src/compilation/build_plan.rs). The\ncompilation process is also responsible for generating documentation, ABIs\nand the like, along with determining if a cached version of the\nto-be-built package already exists and if so, if the cached version\ncan be used or if the cached copy is invalid and needs to be recompiled.\n\nOne important thing to note here is that depending on the compilation\nflags, the caching policy may need to be updated and the `compiler_driver`\nfunction that is passed into the compilation process may change. However,\nwhat this function should be is determined by the client of the Move\npackage library. In particular, when testing even if we are recompiling\nwith the same flags we cannot cache the root package as we need to compile\nit to generate the test plan that will be used by the unit test runner\nlater on. This gathering of the test plan is inserted into the compilation\nprocess via the `compiler_driver` function that is passed in by the client.\nIn this case, the [`../move-cli/src/package`](../move-cli/src/package) is\nthe client and it is responsible for supplying the correct function as the\ncompiler driver to collect the test plan and to later pass that to the unit\ntest runner.\n","frontmatter":{"id":"move-package","title":"Move Package","custom_edit_url":"https://github.com/move-language/move/edit/main/language/tools/move-package/README.md"},"isInternal":false,"tokens":1161,"sizeBytes":5387},{"name":"README.md","path":"third_party/move/tools/move-unit-test/README.md","rawUrl":"https://raw.githubusercontent.com/aptos-labs/aptos-core/HEAD/third_party/move/tools/move-unit-test/README.md","title":"move-unit-test Documentation","category":"plugin-manifest","format":"markdown","content":"---\nid: move-unit-test\ntitle: Move Unit Testing Framework\ncustom_edit_url: https://github.com/move-language/move/edit/main/language/tools/move-unit-test/README.md\n---\n\n# Summary\n\nThis crate defines the core logic for running and reporting Move unit\ntests. Move unit testing is made up of two main components; a test runner,\nand a test reporter.\n\nIt's important to also note here that unit tests can be run using the\n[stackless bytecode interpreter](../../move-prover/interpreter). If the\nunit tests are run with the stackless bytecode interpreter and the test\nreturns a value, then the result of executing the unit test with the Move\nVM and the result of the interpreter will be compared and an error will\nbe raised if they are not equal.\n\nDetailed information on how to use unit tests as a user of Move can be\nfound [here](https://move-language.github.io/move/unit-testing.html).\n\n## Test Runner\n\nThe test runner consumes a\n[`TestPlan`](../../move-compiler/src/unit_test/mod.rs): this is a\ndatastructure that is built by the Move compiler, based on source `#[test]`\nattributes. At a high level, this test plan consists of:\n1. A list of `ModuleTestPlan`s for each non-dependency module. A\n `ModuleTestPlan` consists of a list of unit tests declared in a module,\n along with its arguments and whether the unit test is an expected\n failure or not.\n2. Compiled modules for each source module, along with compiled modules for\n all transitive dependencies.\n3. The source text and source maps for every source and transitive dependency.\n\nThe test runner takes this `TestPlan` along with various configuration\noptions (e.g., number of threads). From this information the test runner\ncreates an initial test state consisting solely of the modules in bullet\n(2) above. This will be the same initial state for all unit tests.\n\nAfter constructing this initial state, a work queue of `ModuleTestPlan`s is\npassed to a [`rayon`](https://docs.rs/rayon/latest/rayon/) threadpool to\nexecute. After the execution of each test a `PASS`, `FAIL` or `TIMEOUT` is\nreported to the writer (usually `std::io::stdout`) as soon as the test's\nresult is known. The result of running tests in a `ModuleTestPlan` is a\nmapping of failing and passing tests (where failing means that the tests\nfailed when it was expected to fail, or vis versa) along with profiling\ninformation and failure information if applicable. These test statistics\nfor each module are combined in parallel and produce a `TestResults` data\nstructure.\n\n## Test Reporter\n\nAfter all of the unit tests have been run and a `TestResults` data\nstructure has been created, the test reporter will iterate through the test\nresults, and will use the data in the `TestFailure` info along with the\nsource maps and source text in the test plan to display source-level error\nmessages for any failing tests.\n\nDepending on the options passed to the unit testing framework, additional\ninfo, such as the global storage state at the point of error for each\nfailing test, or the execution time and number of instructions for each\ntest may be display at the end of a test run.\n","frontmatter":{"id":"move-unit-test","title":"Move Unit Testing Framework","custom_edit_url":"https://github.com/move-language/move/edit/main/language/tools/move-unit-test/README.md"},"isInternal":false,"tokens":698,"sizeBytes":3102},{"name":"README.md","path":"third_party/move/tools/README.md","rawUrl":"https://raw.githubusercontent.com/aptos-labs/aptos-core/HEAD/third_party/move/tools/README.md","title":"tools Documentation","category":"plugin-manifest","format":"markdown","content":"---\nid: tools\ntitle: Move Tools\ncustom_edit_url: https://github.com/move-language/move/edit/main/language/tools/README.md\n---\n\n# Summary\n\nMove has a number of tools associated with it. This directory contains all,\nor almost all of them. The following crates in this directory are libraries\nthat are used by the [`move-cli`](./move-cli) `package` subcommand:\n\n* `move-bytecode-viewer`\n* `move-disassembler`\n* `move-explain`\n* `move-unit-test`\n* `move-package`\n* `move-coverage`\n\nIn this sense each of these crates defines the core logic for a specific\npackage command, e.g., how to run and report unit tests, or collect and\ndisplay test coverage information. However, the Move CLI is responsible for\nstitching these commands together, e.g., when running a move unit test the\nMove CLI is responsible for first making sure the package was built in\n`test` mode ( using the `move-package` library), collecting the test plan\nto feed to the `move-unit-test` library, and returning a non-zero error\ncode if a test fails.\n\nGenerally, if you want to see how various tools interact with each other,\nor how a normal Move user would interact with these tools, you should first\nlook at the Move CLI (specifically the `package` subdirectory/command) as\nthat is responsible for stitching everything together. If you are looking\nfor where the logic for a specific tool is defined, this is most likely in\nthe specific crate for that tool (e.g., if you want to see how TUIs are\nhandled for the `move-bytecode-viewer` that's defined in the\n`move-bytecode-viewer` crate, and not the `move-cli` crate).\n\nSome of the crates mentioned above are also binaries at the moment, however\nthey should all be able to be made libaries only, with the possible\nexception of the `move-coverage` crate. The primary reason for this, is\nthat this tool can collect and report test coverage statistics across\nmultiple packages, and multiple runs over a package. This functionality is\nimportant if you have a large functional test suite such as Diem's and want\nto gather coverage information across all of them.\n\nThe `move-resource-viewer`, and `read-write-set` similarly are library\ncrates that are used by and exposed by the Move CLI, but not through the\n`package` subcommand.\n\nThe `move-bytecode-utils` crates holds general\nutilities for working with Move bytecode, e.g., computing the dependency\norder for modules.\n","frontmatter":{"id":"tools","title":"Move Tools","custom_edit_url":"https://github.com/move-language/move/edit/main/language/tools/README.md"},"isInternal":false,"tokens":548,"sizeBytes":2377}],"systemPromptSnippet":"\n\n# Moved to https://aptos-labs.github.io/framework-book/aptos-experimental/large_packages.html\n\n\nThis crate contains an extension to the Move language with large-scale storage tables.\n\nIn order to use this extension with the Move CLI and package system, you need to compile with\n`feature = [\"table-extension\"]`.\n\nIn order to use this extension in your adapter, you do something as follows:\n\n```rust\nuse move_core_types::account_address::AccountAddress;\nuse move_stdlib::natives;\nuse move_table_extension::NativeTableContext;\nuse move_vm_runtime::move_vm::MoveVM;\nuse move_vm_runtime::native_functions::NativeContextExtensions;\n\nfn run() {\n let resource_resolver = unimplemented!(); // a resource resolver the adapter provides\n let txn_hash = unimplemented!(); // a unique hash for table creation for this transaction\n let table_resolver = unimplemented!(); // a remote table resolver the adapter provides\n let std_addr = unimplemented!(); // address where to deploy the std lib\n let extension_addr = unimplemented!(); // address where to deploy the table extension\n\n let mut extensions = NativeContextExtensions::default();\n extensions.add(NativeTableContext::new(txn_hash, table_resolver));\n let mut natives = move_stdlib::natives::all_natives(std_addr);\n natives.append(&mut move_table_extension::table_natives(extension_addr));\n let vm = MoveVM::new(natives);\n\n let session = vm.new_session_with_extensions(resource_resolver, extensions);\n let result = session.execute_function(..)?;\n let (change_set, events, extensions) = session.finish_with_extensions()?;\n let table_change_set = extensions.get::().into_change_set();\n\n // Do something with the table change set\n // ...\n}\n```\n\n\nThis tree contains extensions to the Move core language and runtime. Those extensions are not enabled by\ndefault but can be integrated into a Move-based environment following the instructions found for each individual\nextension.\n\nSome extensions may eventually become part of the core language after some period of stabilization.\n\n\nThis folder contains a Move package consisting of core Move modules defining functionalities needed by\nany Diem-based blockchains. To start your own Diem-based blockchain, you can create a Move package that\ndepends on this core package and write your own wrapper modules for the account module as well as the\non-chain configuration modules. [`experimental` folder](../experimental) provides an example of such\nMove package.\n\nNext we briefly describe how to write the wrapper modules and how Move's powerful type system can provide flexibility\nas well as safety for your chain.\n\nYou will need to write wrapper modules for the following core modules:\n- Account\n- CoreGenesis\n- DiemConsensusConfig\n- DiemSystem\n- DiemVersion\n- DiemVMConfig\n- ParallelExecutionConfig\n- ValidatorConfig\n- ValidatorOperatorConfig\n\n\nEvery module in this list contains the following resources and functions:\n- A chain marker resource with a `phantom T` type parameter\n- An initialization function that has to be called during chain-specific genesis and publishes a chain marker resource under\n `@CoreResources` address as well as any relevant configuration resources\n- At least one setter function that requires a `Cap` as parameter and modifies the configuration resource(s).\n And at the beginning of the function we check the existence of the chain marker resource.\n\n#### Why is the chain marker resource needed?\n\nWe want to provide the safety guarantee that only the authorized wrapper module can define access\ncontrol policies for the resources. Therefore, we need to make sure that only the wrapper module can call the public\nsetter functions. However, we are designing for wrapper modules that don't even exist right now, so we have to somehow\n\"register\" the wrapper module at the chain-specific genesis. The solution to this question is the chain marker resource.\nThis resource has a phantom type parameter that should be instantiated with a type owned by the wrapper module such as\n`ExperimentalVersion` resource. Each setter function requires a capability parameter instantiated with this type. Since\nthe acquisition of this capability requires a value of this witness type and this type is owned by the wrapper module,\nwe know for sure that only the wrapper module can decide who or which module is allowed to modify the configurations.\n\n#### How to write wrapper modules?\n\nRead `DiemVersion.move` and then `ExperimentalVersion.move` to get the idea.\n\n\n# Move CLI\n\nThe Move command-line interface (Move CLI) is a tool that provides an easy way to interact with Move, to experiment\nwith writing and running Move code, and to experiment with developing new tools useful\nfor Move development. To reflect this, the Move CLI commands are grouped into\nthree main subcommands:\n* **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.\n* **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.\n* **experimental commands**: are experimental commands that are currently in development.\n\nEvery Move CLI command, with the exception of `package create`, is expected to be run within the context of a [Move package](https://move-language.github.io/move/packages.html).\n\n## Installation\n```shell\n$ cargo install --path move/language/tools/move-cli\n```\nor\n```shell\n$ cargo install --git https://github.com/move-language/move move-cli --branch main\n```\n\nThis will install the `move` binary in your Cargo binary directory. On\nmacOS and Linux this is usually `~/.cargo/bin`. You'll want to make sure\nthis location is in your `PATH` environment variable.\n\nNow you should be able to run the Move CLI:\n\n```shell\n$ move\nMove 0.1.0\nCLI frontend for Move compiler and VM\n\nUSAGE:\n move [FLAGS] [OPTIONS] \n ...\n```\n\nWe'll go through the most common Move CLI commands and flags here, however\nyou can find the complete list of commands available by calling `move\n--help`. Additionally, the complete list of flags and options available\nfor each Move CLI command can be found by passing the `--help` flag to it,\ni.e., `move --help`.\n\n## Package Commands\n\nPackage commands provide wrappers with sane defaults around other commands\nthat are provided either by various Move tools, compiler, or prover.\n\nThe `move new` command will create a new empty Move package:\n```shell\n$ move new # Create a Move package under the current dir\n$ move new -p # Create a Move package under path \n```\n\nFrom within a package's root directory, you can build the modules and/or scripts that you have written in the package with:\n```shell\n$ move build # Builds the Move package you are currently in\n$ move build -p # Builds the Move package at \n```\n\nThe compiled artifacts will by default be stored in the `build` directory. You\ncan change where the build artifacts are saved by passing the optional `--build-dir` flag:\n\n```shell\n$ move build --build-dir # Build current Move package and save artifacts under \n```\n\nYou can verify the specifications in a Move package using the Move Prover with the `prove` command:\n\n```shell\n$ move prove # Verify the specifications in the current package\n$ move prove -p # Verify the specifications in the package at \n```\n\nIn order to run the Move Prover [additional tools need to be\ninstalled](https://github.com/move-language/move/blob/main/language/move-prover/doc/user/install.md).\nInformation on the Move Prover and its configuration options can be found\n[here](https://github.com/move-language/move/blob/main/language/move-prover/doc/user/prover-guide.md)\nand\n[here](https://github.com/move-language/move/blob/main/language/move-prover/doc/user/spec-lang.md).\n\nYou can also run unit tests in a package using the `test` command\n\n```shell\n$ move test # Run Move unit tests in the current package\n$ move test -p # Run Move unit tests in the package at \n```\n## Sandbox Commands\n\nThe sandbox allows you to experiment with writing and running Move code without\nvalidators, a blockchain, or transactions. Persistent data is stored on-disk in\na directory structure that mimics the Move memory model\n\n### Project structure\n\nEach sandbox command is run in the context of a Move package. So let's create a\nMove package that we'll use for the code in this README and `cd` into it:\n\n```shell\n$ move new readme\n$ cd readme\n```\n\n### Compiling and running scripts\n\nLet's first start out with a simple script that prints its [`signer`](https://move-language.github.io/move/signer.html).\nCreate a file named `sources/debug_script.move` and type the following into it:\n\n```rust\n// sources/debug_script.move\nscript {\nuse std::debug;\nfun debug_script(account: signer) {\n debug::print(&account)\n}\n}\n```\n\nBefore we can run this however, we need to import the Move standard library\nnursery in order to have access to the `Debug` module and `Std` [named\naddress](https://move-language.github.io/move/address.html#named-addresses).\nYou can specify dependencies locally, or using a Git URL. Here, we will specify\nit using Git, so add the following to the `Move.toml` file in the `readme`\ndirectory:\n\n```toml\n[addresses]\nstd = \"0x1\" # Specify and assign 0x1 to the named address \"std\"\n\n[dependencies]\nMoveNursery = { git = \"https://github.com/move-language/move.git\", subdir = \"language/move-stdlib/nursery\", rev = \"main\" }\n# ^ ^ ^ ^\n# Git dependency Git clone URL Subdir under git repo (optional) Git revision to use\n```\n\nNow let's try running the script -- the very first time may take some time since the package command will clone the repository at the given URL, but subsequent calls should be fast:\n\n```shell\n$ move sandbox run sources/debug_script.move --signers 0xf\n[debug] (&) { 0000000000000000000000000000000f }\n```\n\nThe `--signers 0xf` argument indicates which account address(es) have signed\noff on the script. Omitting `--signers` or passing multiple signers to this\nsingle-`signer` script will trigger a type error.\n\n### Passing arguments\n\nThe CLI supports passing non-`signer` arguments to `move sandbox run` via `--args`. The following argument types are supported:\n* `bool` literals (`true`, `false`)\n* `u64` literals (e.g., `10`, `58`)\n* `address` literals (e.g., `0x12`, `0x0000000000000000000000000000000f`)\n* hexadecimal strings (e.g., `'x\"0012\"'` will parse as the `vector` value `[00, 12]`)\n* ASCII strings (e.g., `'b\"hi\"'` will parse as the `vector` value `[68, 69]`)\n\n### Publishing new modules\n\nWhen executing a transaction script you'll often want to call into different\nMove modules, like in the example above with the `Debug` module. New modules can\nbe added to the `sources` directory in the package where the CLI is being\ninvoked. You can also add dependencies on other packages to have access to the\nmodules that they define (just like we did with the `Debug` module above). The\n`move sandbox run` command will compile and publish each module in the package, and\nin each of the package's transitive dependencies, before running the given script.\n\nTry saving this code in `sources/Test.move`:\n\n```rust\n// sources/Test.move\nmodule 0x2::Test {\n use std::signer;\n\n struct Resource has key { i: u64 }\n\n public fun publish(account: &signer) {\n move_to(account, Resource { i: 10 })\n }\n\n public fun write(account: &signer, i: u64) acquires Resource {\n borrow_global_mut(signer::address_of(account)).i = i;\n }\n\n public fun unpublish(account: &signer) acquires Resource {\n let Resource { i: _ } = move_from(signer::address_of(account));\n }\n}\n```\n\nNow, try\n\n```shell\n$ move build\n```\n\nThis will cause the CLI to compile and typecheck the modules under\n`sources`, but it won't publish the module bytecode under `storage`. You can\ncompile and publish the module by running the `move sandbox publish` command\n(here we pass the `-v` or verbose flag to get a better understanding of what's\nhappening):\n\n```shell\n$ move sandbox publish -v\nFound 1 modules\nPublishing a new module 00000000000000000000000000000002::Test (wrote 253 bytes)\nWrote 253 bytes of module ID's and code\n```\n\nNow, if we take a look under `storage`, we will see the published bytecode\nfor our `Test` module:\n\n```shell\n$ ls storage/0x00000000000000000000000000000002/modules\nTest.mv\n```\n\nWe can also inspect the compiled bytecode in storage using `move sandbox view`:\n\n```shell\n$ move sandbox view storage/0x00000000000000000000000000000002/modules/Test.mv\nmodule 2.Test {\nstruct Resource has key {\n i: u64\n}\n\npublic publish() {\n 0: MoveLoc[0](Arg0: &signer)\n 1: LdU64(10)\n 2: Pack[0](Resource)\n 3: MoveTo[0](Resource)\n 4: Ret\n}\npublic unpublish() {\n 0: MoveLoc[0](Arg0: &signer)\n 1: Call[3](address_of(&signer): address)\n 2: MoveFrom[0](Resource)\n 3: Unpack[0](Resource)\n 4: Pop\n 5: Ret\n}\npublic write() {\n 0: CopyLoc[1](Arg1: u64)\n 1: MoveLoc[0](Arg0: &signer)\n 2: Call[3](address_of(&signer): address)\n 3: MutBorrowGlobal[0](Resource)\n 4: MutBorrowField[0](Resource.i: u64)\n 5: WriteRef\n 6: Ret\n}\n}\n```\n\nYou can also look at the compiled bytecode before publishing to `storage` by\nrunning either `move disassemble --name ` or `move\ndisassemble --name --interactive` to interactively inspect the\nbytecode and how it relates to the Move source code:\n\n```shell\n$ move disassemble --name Test --interactive # You can quit by pressing \"q\"\n$ move disassemble --name Test\n// Move bytecode v4\nmodule 2.Test {\nstruct Resource has key {\n i: u64\n}\n\npublic publish() {\nB0:\n 0: MoveLoc[0](account: &signer)\n 1: LdU64(10)\n 2: Pack[0](Resource)\n 3: MoveTo[0](Resource)\n 4: Ret\n}\npublic unpublish() {\nB0:\n 0: MoveLoc[0](account: &signer)\n 1: Call[3](address_of(&signer): address)\n 2: MoveFrom[0](Resource)\n 3: Unpack[0](Resource)\n 4: Pop\n 5: Ret\n}\npublic write() {\nB0:\n 0: CopyLoc[1](i: u64)\n 1: MoveLoc[0](account: &signer)\n 2: Call[3](address_of(&signer): address)\n 3: MutBorrowGlobal[0](Resource)\n 4: MutBorrowField[0](Resource.i: u64)\n 5: WriteRef\n 6: Ret\n}\n}\n```\n\n### Updating state\n\nLet's exercise our new `Test` module by running the following script:\n\n```rust\n// sources/test_script.move\nscript {\nuse 0x2::Test;\nfun test_script(account: signer) {\n Test::publish(&account)\n}\n}\n```\n\nThis script invokes the `publish` function of our `Test` module, which will\npublish a resource of type `Test::Resource` under the signer's account.\nLet's first see what this script will change without committing those\nchanges first. We can do this by passing the `--dry-run` flag:\n\n```shell\n$ move sandbox run sources/test_script.move --signers 0xf -v --dry-run\nCompiling transaction script...\nChanged resource(s) under 1 address(es):\n Changed 1 resource(s) under address 0000000000000000000000000000000f:\n Added type 0x2::Test::Resource: [10, 0, 0, 0, 0, 0, 0, 0] (wrote 40 bytes)\nWrote 40 bytes of resource ID's and data\n key 0x2::Test::Resource {\n i: 10\n }\nDiscarding changes; re-run without --dry-run if you would like to keep them.\n```\n\nEverything looks good, so we can run this again, but this time commit the\nchanges by removing the `--dry-run` flag:\n\n```shell\n$ move sandbox run sources/test_script.move --signers 0xf -v\nCompiling transaction script...\nChanged resource(s) under 1 address(es):\n Changed 1 resource(s) under address 0000000000000000000000000000000f:\n Added type 0x2::Test::Resource: [10, 0, 0, 0, 0, 0, 0, 0] (wrote 40 bytes)\nWrote 40 bytes of resource ID's and data\n key 0x2::Test::Resource {\n i: 10\n }\n```\n\nWhile the verbose flag used above (`-v`) shows resource changes, it is also\npossible to view them manually.\nWe can inspect the newly published resource using `move sandbox view` since\nthe change has been committed:\n\n```shell\n$ move sandbox view storage/0x0000000000000000000000000000000f/resources/0x00000000000000000000000000000002::Test::Resource.bcs\nkey 0x2::Test::Resource {\n i: 10\n}\n```\n\n#### Cleaning state\n\nSince state persists from one call to the Move CLI to another, there will\nfrequently be times where you want to start again at a clean state. This\ncan be done using the `move sandbox clean` command which will remove the\n`storage` and `build` directories:\n\n```shell\n$ move sandbox view storage/0x0000000000000000000000000000000f/resources/0x00000000000000000000000000000002::Test::Resource.bcs\nresource 0x2::Test::Resource {\n i: 10\n}\n$ move sandbox clean\n$ move sandbox view storage/0x0000000000000000000000000000000f/resources/0x00000000000000000000000000000002::Test::Resource.bcs\nError: `move sandbox view ` must point to a valid file under storage\n```\n\n### Expected Value Testing with the Move CLI\n\nAs mentioned previously, Move has a unit testing framework. However, unit tests\ncannot test everything -- in particular testing for events cannot be easily\ndone. To help with writing tests that need to check for events, and expect\nspecific states, the Move CLI also has a built-in expected-value testing\nframework. Each test is run independently in its own sandbox so state does not\npersist from one test to another.\n\nEach test is structured as a Move package along with an additional `args.txt` file that\nspecifies a sequence of Move CLI commands that should be run in that\ndirectory.\nAdditionally, there must be an `args.exp` file that contain the expected\noutput from running the sequence of Move CLI commands specified in the\n`args.txt` file for that test.\n\nFor example, if we wanted to create a Move CLI test that reran all of the\ncommands that we've seen so far, we could do so by adding an `args.txt`\nto the `readme` directory that we created at the start and that we've been\nadding scripts and modules to:\n\n```\nreadme/\n├── args.txt\n├── Move.toml\n└── sources\n ├── debug_script.move\n ├── Test.move\n └── test_script.move\n```\n\nAnd, where the `args.txt` file contains the following Move CLI commands:\n\n```shell\n$ cd ..\n$ cat readme/args.txt\n## Arg files can have comments!\nsandbox run sources/debug_script.move --signers 0xf\nsandbox run sources/debug_script.move --signers 0xf\nbuild\nsandbox publish\nsandbox view storage/0x00000000000000000000000000000002/modules/Test.mv\nsandbox run sources/test_script.move --signers 0xf -v\nsandbox view storage/0x0000000000000000000000000000000f/resources/0x00000000000000000000000000000002::Test::Resource.bcs\n```\n\nWe can then use the `move sandbox test` command and point it at the `readme` directory to run each of these\nMove CLI commands for us in sequence:\n\n```shell\n$ move sandbox exp-test -p readme\n...\n0 / 1 test(s) passed.\nError: 1 / 1 test(s) failed.\n```\n\nHowever, as we see this test will fail since there is no `args.exp` file for the test\nyet. We can generate this expectation file by setting the `UPDATE_BASELINE`\nenvironment variable when running the test:\n\n```shell\n$ UPDATE_BASELINE=1 move sandbox exp-test -p readme\n1 / 1 test(s) passed.\n```\n\nThere should now be an `args.exp` file under the `readme` directory that\ncontains the expected output of running the sequence of Move CLI commands\nin the `args.txt` file:\n\n```shell\n$ cat readme/args.exp\nCommand `sandbox run sources/debug_script.move --signers 0xf`:\n[debug] (&) { 0000000000000000000000000000000f }\nCommand `sandbox run sources/debug_script.move --signers 0xf --mode bare`:\n...\n```\n\n#### Testing with code coverage tracking\n\nCode coverage has been an important metric in software testing. In Move CLI expected value tests, we\naddress the need for code coverage information with an additional flag,\n`--track-cov`, that can be passed to the `move sandbox exp-test` command.\n\nNote: To view coverage information, the Move CLI must be installed with the `--debug` flag;\ni.e., `cargo install --debug --path move/language/tools/move-cli`.\n\nUsing our running example to illustrate:\n```shell\n$ move sandbox exp-test -p readme --track-cov\n1 / 1 test(s) passed.\nModule 00000000000000000000000000000002::Test\n fun publish\n total: 5\n covered: 5\n % coverage: 100.00\n fun unpublish\n total: 6\n covered: 0\n % coverage: 0.00\n fun write\n total: 7\n covered: 0\n % coverage: 0.00\n>>> % Module coverage: 27.78\n```\n\nThe output indicates that not only the test is passed, but also that 100%\ninstruction coverage is observed in the `publish` funciton. This is expected\nas the whole purpose of our `test_script.move` is to run the `publish` function.\nAt the same time, the other two functions, `unpublish` and `write`, are never\nexecuted, making the average coverage 27.78% for the whole `Test` module.\n\nInternally, Move CLI uses the tracing feature provided by the Move VM to record\nwhich instructions in the compiled bytecode are executed and uses this\ninformation to calculate code coverage. Instruction coverage in Move can\nusually serve the purpose of line coverage in common C/C++/Rust coverage\ntracking tools.\n\nNote that the coverage information is aggregated across multiple `run` commands\nin `args.txt`. To illustrate this, suppose that we have another test script,\n`test_unpublish_script.move`, under `readme/sources` with the following\ncontent:\n\n```rust\nscript {\nuse 0x2::Test;\nfun test_unpublish_script(account: signer) {\n Test::unpublish(&account)\n}\n}\n```\n\nWe further add a new command to the end of `args.txt`\n(`args.exp` needs to be updated too).\n```shell\nsandbox run sources/test_unpublish_script.move --signers 0xf -v\n```\n\nNow we can re-test the `readme` again\n```shell\n$ move sandbox exp-test -p readme --track-cov\n1 / 1 test(s) passed.\nModule 00000000000000000000000000000002::Test\n fun publish\n total: 5\n covered: 5\n % coverage: 100.00\n fun unpublish\n total: 6\n covered: 6\n % coverage: 100.00\n fun write\n total: 7\n covered: 0\n % coverage: 0.00\n>>> % Module coverage: 61.11\n```\n\nThis time, note that the `unpublish` function is 100% covered too and the\noverall module coverage is boosted to 61.11%.\n\n### Detecting breaking changes\n\nThe `move sandbox publish` command automatically detects when upgrading a module may lead to a breaking change.\nThere are two kinds of breaking changes:\n\n* Linking compatibility (e.g., removing or changing the signature of a public function that is invoked by other modules, removing a\nstruct or resource type used by other modules)\n* Layout compatibility (e.g., adding/removing a resource or struct field)\n\nThe breaking changes analysis performed by `move sandbox publish` is necessarily conservative. For example, say we `move sandbox publish` the following\nmodule:\n\n```\naddress 0x2 {\nmodule M {\n struct S has key { f: u64, g: u64 }\n}\n}\n```\n\nand then wish to upgrade it to the following:\n\n```\naddress 0x2 {\nmodule M {\n struct S has key { f: u64 }\n}\n}\n```\n\nRunning `move sandbox publish` on this new version will fail:\n\n```\nBreaking change detected--publishing aborted. Re-run with --ignore-breaking-changes to publish anyway.\nError: Layout API for structs of module 00000000000000000000000000000002::M has changed. Need to do a data migration of published structs\n```\n\nIn this case, we know we have not published any instances of `S` in global storage, so it is safe to re-run `move sandbox publish --ignore-breaking-changes` (as recommended).\nWe can double-check that this was not a breaking change by running `move sandbox doctor`.\nThis handy command runs exhaustive sanity checks on global storage to detect any breaking changes that occurred in the past:\n* All modules pass the bytecode verifier\n* All modules link against their dependencies\n* All resources deserialize according to their declared types\n* All events deserialize according to their declared types\n\n\n---\nid: move-package\ntitle: Move Package\ncustom_edit_url: https://github.com/move-language/move/edit/main/language/tools/move-package/README.md\n---\n\n# Summary\n\nThe Move package crate contains the logic for parsing, resolving, and\nbuilding Move packages. It is meant to be used as a library, both for\nbuilding packages (e.g., by the Move CLI), or by other applications that\nmay be working with Move packages. The package system is split into three\nmain phases: parsing, resolution, and compilation.\n\n## Parsing and Manifest Layout\n\nThe parsing and manifest layout logic is defined in the\n[`./src/source_package`](./src/source_package) directory. This defines the\nlayout and the set of required and optional directories for a Move package\nin [`./src/source_package/layout.rs`](./src/source_package/layout.rs), it\ndefines the format of the parsed Move package manifest (\"`Move.toml`\") in\n[`./src/source_package/parsed_manifest.rs`](./src/source_package/parsed_manifest.rs),\nand it defines the parser for the Move package manifest in\n[`./src/source_package/manifest_parser.rs`](./src/source_package/manifest_parser.rs).\nNote that we don't have a tokenizer/lexer as we use the TOML lexer. This\nalso resolves git dependencies to where they will live on the local file\nsystem (but does not clone them).\n\n## Resolution\n\nThe resolution phase is responsible for resolving all packages and building\nthe package graph which represents the dependency relations between\npackages. It is also responsible for ensuring that all named addresses have\na value assigned to them, and that there are no conflicting assignments.\nThe package graph is rooted at the package being built and is a DAG.\n\nWhen building the package graph we do the following conceptual operations:\nverify that dependencies exist at the declared locations, that their\npackage names and source digests match (if applicable), clone git\ndependencies if they don't already exist locally, build a dependency graph\nof Move packages and ensure this forms a DAG, compute an\nassignment for each named address in each Move package in the package\ngraph, and ensure that the resulting named address assignment is valid.\n\nAll of the above steps are fairly straightforward, with the possible\nexception of named addresses: each package will have a set of in-scope\nnamed addresses. The set of in-scope named addresses for a package `P` is\ndefined as the transitive closure of all named addresses in the\ndependencies of `P`. Additionally, a package can rename named addresses\nthat are in-scope as long as the final assignment of a value to the set of\nnamed addresses can be unified. To ensure that named addresses are\nunifiable across renamings, resolution performs unification across named\naddresses using a `Rc>>`: when a named address first\nenters scope in the package graph a `Rc>` is created for it.\nThis refcell is then shared to all uses of the named address _even across\nrenamings_ and when a value is assigned to it, the value must (1) match the\ncurrent value contained within the `Option`, or (2) the `Option` is `None`,\nand the value is placed into the refcell.\n\n## Compilation\n\nThe final stage of the package system is compilation. All logic relating to\nthe final build artifacts, or global environment creation, is contained in\nthe [`./src/compilation`](./src/compilation) directory. The package layout\nfor compiled Move packages is defined in\n[`./src/compilation/package_layout.rs`](./src/compilation/package_layout.rs).\n\nThe [`./src/compilation/build_plan.rs`](./src/compilation/build_plan.rs)\ncontains the logic for driving the compilation of a package and the\ncompilation of all of the package's dependencies given a valid resolution\ngraph. The logic in\n[`./src/compilation/compiled_package.rs`](./src/compilation/compiled_package.rs)\ncontains the definition of the in-memory representation of compiled Move\npackages and other data structures and APIs relating to compiled Move\npackages, along with the logic for compiling a _single_ Move package\nassuming all of its dependencies are already compiled and saved to disk.\nThis is driven by the logic in\n[`./src/compilation/build_plan.rs`](./src/compilation/build_plan.rs). The\ncompilation process is also responsible for generating documentation, ABIs\nand the like, along with determining if a cached version of the\nto-be-built package already exists and if so, if the cached version\ncan be used or if the cached copy is invalid and needs to be recompiled.\n\nOne important thing to note here is that depending on the compilation\nflags, the caching policy may need to be updated and the `compiler_driver`\nfunction that is passed into the compilation process may change. However,\nwhat this function should be is determined by the client of the Move\npackage library. In particular, when testing even if we are recompiling\nwith the same flags we cannot cache the root package as we need to compile\nit to generate the test plan that will be used by the unit test runner\nlater on. This gathering of the test plan is inserted into the compilation\nprocess via the `compiler_driver` function that is passed in by the client.\nIn this case, the [`../move-cli/src/package`](../move-cli/src/package) is\nthe client and it is responsible for supplying the correct function as the\ncompiler driver to collect the test plan and to later pass that to the unit\ntest runner.\n\n\n---\nid: move-unit-test\ntitle: Move Unit Testing Framework\ncustom_edit_url: https://github.com/move-language/move/edit/main/language/tools/move-unit-test/README.md\n---\n\n# Summary\n\nThis crate defines the core logic for running and reporting Move unit\ntests. Move unit testing is made up of two main components; a test runner,\nand a test reporter.\n\nIt's important to also note here that unit tests can be run using the\n[stackless bytecode interpreter](../../move-prover/interpreter). If the\nunit tests are run with the stackless bytecode interpreter and the test\nreturns a value, then the result of executing the unit test with the Move\nVM and the result of the interpreter will be compared and an error will\nbe raised if they are not equal.\n\nDetailed information on how to use unit tests as a user of Move can be\nfound [here](https://move-language.github.io/move/unit-testing.html).\n\n## Test Runner\n\nThe test runner consumes a\n[`TestPlan`](../../move-compiler/src/unit_test/mod.rs): this is a\ndatastructure that is built by the Move compiler, based on source `#[test]`\nattributes. At a high level, this test plan consists of:\n1. A list of `ModuleTestPlan`s for each non-dependency module. A\n `ModuleTestPlan` consists of a list of unit tests declared in a module,\n along with its arguments and whether the unit test is an expected\n failure or not.\n2. Compiled modules for each source module, along with compiled modules for\n all transitive dependencies.\n3. The source text and source maps for every source and transitive dependency.\n\nThe test runner takes this `TestPlan` along with various configuration\noptions (e.g., number of threads). From this information the test runner\ncreates an initial test state consisting solely of the modules in bullet\n(2) above. This will be the same initial state for all unit tests.\n\nAfter constructing this initial state, a work queue of `ModuleTestPlan`s is\npassed to a [`rayon`](https://docs.rs/rayon/latest/rayon/) threadpool to\nexecute. After the execution of each test a `PASS`, `FAIL` or `TIMEOUT` is\nreported to the writer (usually `std::io::stdout`) as soon as the test's\nresult is known. The result of running tests in a `ModuleTestPlan` is a\nmapping of failing and passing tests (where failing means that the tests\nfailed when it was expected to fail, or vis versa) along with profiling\ninformation and failure information if applicable. These test statistics\nfor each module are combined in parallel and produce a `TestResults` data\nstructure.\n\n## Test Reporter\n\nAfter all of the unit tests have been run and a `TestResults` data\nstructure has been created, the test reporter will iterate through the test\nresults, and will use the data in the `TestFailure` info along with the\nsource maps and source text in the test plan to display source-level error\nmessages for any failing tests.\n\nDepending on the options passed to the unit testing framework, additional\ninfo, such as the global storage state at the point of error for each\nfailing test, or the execution time and number of instructions for each\ntest may be display at the end of a test run.\n\n\n---\nid: tools\ntitle: Move Tools\ncustom_edit_url: https://github.com/move-language/move/edit/main/language/tools/README.md\n---\n\n# Summary\n\nMove has a number of tools associated with it. This directory contains all,\nor almost all of them. The following crates in this directory are libraries\nthat are used by the [`move-cli`](./move-cli) `package` subcommand:\n\n* `move-bytecode-viewer`\n* `move-disassembler`\n* `move-explain`\n* `move-unit-test`\n* `move-package`\n* `move-coverage`\n\nIn this sense each of these crates defines the core logic for a specific\npackage command, e.g., how to run and report unit tests, or collect and\ndisplay test coverage information. However, the Move CLI is responsible for\nstitching these commands together, e.g., when running a move unit test the\nMove CLI is responsible for first making sure the package was built in\n`test` mode ( using the `move-package` library), collecting the test plan\nto feed to the `move-unit-test` library, and returning a non-zero error\ncode if a test fails.\n\nGenerally, if you want to see how various tools interact with each other,\nor how a normal Move user would interact with these tools, you should first\nlook at the Move CLI (specifically the `package` subdirectory/command) as\nthat is responsible for stitching everything together. If you are looking\nfor where the logic for a specific tool is defined, this is most likely in\nthe specific crate for that tool (e.g., if you want to see how TUIs are\nhandled for the `move-bytecode-viewer` that's defined in the\n`move-bytecode-viewer` crate, and not the `move-cli` crate).\n\nSome of the crates mentioned above are also binaries at the moment, however\nthey should all be able to be made libaries only, with the possible\nexception of the `move-coverage` crate. The primary reason for this, is\nthat this tool can collect and report test coverage statistics across\nmultiple packages, and multiple runs over a package. This functionality is\nimportant if you have a large functional test suite such as Diem's and want\nto gather coverage information across all of them.\n\nThe `move-resource-viewer`, and `read-write-set` similarly are library\ncrates that are used by and exposed by the Move CLI, but not through the\n`package` subcommand.\n\nThe `move-bytecode-utils` crates holds general\nutilities for working with Move bytecode, e.g., computing the dependency\norder for modules.\n"}