From 71e9bd1b0c0f025cf3431e71ed032bb90fbef38d Mon Sep 17 00:00:00 2001 From: ronny-mysten <118224482+ronny-mysten@users.noreply.github.com> Date: Tue, 14 Mar 2023 16:03:44 -0600 Subject: [PATCH] Move.lock (#9297) ## Description Describe the changes or additions included in this PR. Separate PR for nav to follow. ## Test Plan Local --- If your changes are not user-facing and not a breaking change, you can skip the following section. Otherwise, please indicate what changed, and then add to the Release Notes section as highlighted during the release process. ### Type of Change (Check all that apply) - [ ] user-visible impact - [ ] breaking change for a client SDKs - [ ] breaking change for FNs (FN binary must upgrade) - [ ] breaking change for validators or node operators (must upgrade binaries) - [ ] breaking change for on-chain data layout - [ ] necessitate either a data wipe or data migration ### Release notes --------- Co-authored-by: Randall-Mysten <109545725+randall-Mysten@users.noreply.github.com> --- doc/in-progress/move_lock_file.md | 11 --------- doc/src/build/move/lock-file.md | 37 +++++++++++++++++++++++++++++++ 2 files changed, 37 insertions(+), 11 deletions(-) delete mode 100644 doc/in-progress/move_lock_file.md create mode 100644 doc/src/build/move/lock-file.md diff --git a/doc/in-progress/move_lock_file.md b/doc/in-progress/move_lock_file.md deleted file mode 100644 index 1474b342b0dba..0000000000000 --- a/doc/in-progress/move_lock_file.md +++ /dev/null @@ -1,11 +0,0 @@ -# `Move.lock` file for Move packages - -## What is it and what do I do with it? - -The `Move.lock` file is automatically created when you build a `Move` package. It contains data about your package (like dependencies). This aids operations like verifying your source code against on-chain packages and ensures compatibility with package managers. - -Do: check in the generated `Move.lock` file if you use source control. It will be created in your package root (where `Move.toml` is). - -Don't: Manually edit the `Move.lock` file by hand, or move it to another directory. - -A full technical description of the [original design is available](https://docs.google.com/document/d/1OV3te-SnpZv2Yxv7uxGQH6NFhE-CdqiCjB66JmYAGKs/edit#heading=h.byj11m1l42gu), which describes the schema, including headers like `[dependencies]` found in the `Move.lock` file. diff --git a/doc/src/build/move/lock-file.md b/doc/src/build/move/lock-file.md new file mode 100644 index 0000000000000..dcdda0653b9a1 --- /dev/null +++ b/doc/src/build/move/lock-file.md @@ -0,0 +1,37 @@ +--- +title: `Move.lock` File for Move Packages +--- + +When you build a Move package, the process creates a `Move.lock` file at the root of your package. The file acts as a communication layer between the Move compiler and other tools, like chain-specific command line interfaces and third-party package managers. The `Move.lock` file contains information about your package, including its dependencies, that aids operations like verification of source code against on-chain packages and package manager compatibility. + +Like the [`Move.toml'](manifest.md) file, the `Move.lock` file is a text-based `toml` file. Unlike the package manifest, the `Move.lock` file is not intended for you to edit directly. Processes on the toolchain, like the Move compiler, access and edit the file to read and append relevant information. You also must not move the file from the root, as it needs to be at the same level as your `Move.toml` manifest. + +If you are using source control for your package, make sure the `Move.lock` file is checked in to your repository. This ensures every build of your package is an exact replica of the original. + +## On-chain source verification + +`Move.lock` records the toolchain version and flags passed during package compilation so the compiler can replicate the process. This provides confirmation that the package found at a given address on chain originated from a specific source package. Having this data in the lock file means you don't have to manually provide this information, which would be time consuming and prone to error. + +## Dependency resolution + +When you build a package, the Move compiler resolves dependencies in `Move.toml`. After each resolution, the compiler writes the location of a dependency to the `Move.lock` file. If a dependency fails to resolve, the compiler stops writing to the `Move.lock` file and the build fails. If all dependencies resolve, the `Move.lock` file contains the locations (local and remote) of all your package's transitive dependencies. The `Move.lock` file stores the name and package details in an array similar to the following: + +``` +[[move.dependency]] +name = “A” +source = { git = “https://github.com/b/c.git”, subdir = “e/f”, rev = “a1b2c3” } + +[[move.dependency]] +name = “B” +source = { local = “../local-dep” } + +[[move.dependency]] +name = “C” +source = { git = “https://github.com/a/b.git”, rev = “d1e2f3”, subdir = “c” } + +[[move.dependency]] +name = “D” +source = { address = “0xa1b2…3z” } +``` + +