Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[trace-debug] Marketplace release prep #20341

Merged
merged 4 commits into from
Nov 20, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -1,7 +1,9 @@
# Move

Provides language support for the Move programming language. For information about Move visit the
language [documentation](https://docs.sui.io/concepts/sui-move-concepts).
language [documentation](https://docs.sui.io/concepts/sui-move-concepts). It also provides early-stage
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But this isn't actually true, right? It lets you run the tracing command, it requires another extension to do trace debugging.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For all intents and purposes it's true. When someone installs Move extension (after the next update of course), the Move Trace Debugging extension is installed automatically so from developer's perspective it's this extension that provides it (much like syntax highlighting is provided by a different extension and yet we list this feature in this README) The debugging instructions comment in the "Features" section clarifies this by saying that "This functionality is provided by automatically including Move Trace Debugging extension" (I did not think we need this particular piece of info right in at the top of this README page)

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Okay, could we say "The dependent extension, ${fully qualified extension name}, also provides..." just to be explicit?

Copy link
Contributor Author

@awelc awelc Nov 20, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We do say that later in the README where we describe how to actually trace-debug Move code:

"If the opened Move source file is located within a buildable project, and you have the sui binary installed, you can trace-debug execution of Move unit tests within this project. This functionality is provided by this (Move) extension automatically including the Move Trace Debugging extension"

Not sure why we should throw this particular piece of information at the user right at the start, particularly that we don't at all mention that syntax highlighting is provided the same way (through a separate extension), unless you think we should do it as well. That being said, if you think it's crucial, I am not that strongly opposed to adding this info at the beginning, but still wanted to cast my vote here

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am going to land it as is but happy to change it (or stamp a change) if need be

support for trace-debugging Move unit tests using a familiar VSCode debugging interface (e.g., stepping
through the code, tracking local variable names, setting line breakpoints).

# How to Install

Expand All @@ -28,7 +30,7 @@ its custom location location using VSCode's settings (`⌘` + `,` on macOS, or u
Preferences > Settings*). Search for the `move.sui.path` user setting, set it to the new location of
the `sui` binary, and restart VSCode.

In order to trace Move code execution, the `sui` binary must be built with the `tracing` feature flag.
In order to trace-debug Move code execution, the `sui` binary must be built with the `tracing` feature flag.
If your version of the `sui` binary was not built with this feature flag, an attempt to trace test
execution will fail. In this case you may have to build the `sui` binary from source following these
[instructions](https://docs.sui.io/guides/developer/getting-started/sui-install#install-sui-binaries-from-source).
Expand Down Expand Up @@ -70,7 +72,6 @@ move-analyzer binary already exists in the default location (`~/.sui/bin` on mac
`C:\Users\USER\.sui\bin` on Windows), delete the existing move-analyzer binary and reinstall the
extension.


## What if everything else fails?

Check [Sui Developer Forum](https://forums.sui.io/c/technical-support) to see if the problem
Expand Down Expand Up @@ -101,8 +102,18 @@ Move source file (a file with a `.move` file extension) and:
- inlay hints:
- types: local declarations, lambda parameters, variant and struct pattern matching
- parameter names at function calls
- If the opened Move source file is located within a buildable project you can build and (locally)
- If the opened Move source file is located within a buildable project, and you have the `sui`
binary installed, you can build and (locally)
test this project using `Move: Build a Move package` and `Move: Test a Move package` commands from
VSCode's command palette. You can also enable Move trace generation during test execution
using `Move: Trace Move package execution` command from VSCode's command palette (traces will
be available in the `traces` directory in JSON format).
VSCode's command palette.
- If the opened Move source file is located within a buildable project, and you have the `sui`
binary installed, you can trace-debug execution of Move unit tests within this project.
This functionality is provided by this (Move) extension automatically including the Move Trace Debugging
[extension](https://marketplace.visualstudio.com/items?itemName=mysten.move-trace-debuggin). Go to
the Move Trace Debugging extension link to find more detailed information about trace-debugging and
the current level of support. Trace-debugging a Move unit test is a two-step process:
- first, you need to generate traces for Move unit tests by using `Move: Trace Move test execution`
command from VSCode's command palette (traces will be available in the `traces` directory in JSON format)
- second, you need to execute `Run->Start Debugging` menu command with Move file containing the test
you want to trace-debug opened (if the file contains multiple tests, you will be able to select a specific one
from a drop-down menu)
Original file line number Diff line number Diff line change
Expand Up @@ -157,8 +157,9 @@
"publish": "npm run pretest && npm run test && vsce publish"
},
"extensionDependencies": [
"damirka.move-syntax"
],
"damirka.move-syntax",
"mysten.move-trace-debug"
],
"dependencies": {
"command-exists": "^1.2.9",
"lru-cache": "^4.1.3",
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,137 @@
#!/bin/zsh
# Copyright (c) Mysten Labs, Inc.
# SPDX-License-Identifier: Apache-2.0

# This script is meant to be executed on MacOS (hence zsh use - to get associative arrays otherwise
# unavailable in the bundled bash version).
#
# Before running the script, you need to download Sui binaries to a freshly created directory
# (make sure that there are no other files in this directory). Sui binary must be a compressed
# tarball (with tgz extension) and its name has to have the following format:
# sui-VERSION-SHA-PLATFORM.tgz
#
# where:
# - VERSION is the Sui binary version (e.g., "v.1.37.0)
# - SHA is first 10 characgers of commit sha for the version of Sui repo's main branch
# that this binary was build from
# - PLATFORM is on of the supported platforms (macos-arm64, macos-x86_64, ubuntu-x86_64, windows-x86_64)
set -e

usage() {
SCRIPT_NAME=$(basename "$1")
>&2 echo "Usage: $SCRIPT_NAME -pkg|-pub [-h] BINDIR"
>&2 echo ""
>&2 echo "Options:"
>&2 echo " -pub Publish extensions for all targets"
>&2 echo " -pkg Package extensions for all targets"
>&2 echo " -h Print this message"
>&2 echo " BINDIR Directory containing pre-built Sui binaries"
}

clean_tmp_dir() {
test -d "$TMP_DIR" && rm -fr "$TMP_DIR"
}

if [[ "$@" == "" ]]; then
usage $0
exit 1
fi

BIN_DIR=""
for cmd in "$@"
do
if [[ "$cmd" == "-h" ]]; then
usage $0
exit 0
elif [[ "$cmd" == "-pkg" ]]; then
OP="package"
OPTS="-omove-VSCODE_OS.vsix"
elif [[ "$cmd" == "-pub" ]]; then
OP="publish"
OPTS=""
else
BIN_DIR=$cmd

if [[ ! -d "$BIN_DIR" ]]; then
echo Sui binary directory $BIN_DIR does not exist
usage $0
exit 1
fi
fi
done

if [[ $BIN_DIR == "" ]]; then
# directory storing Sui binaries have not been defined
usage $0
exit 1
fi

# a map from os version identifiers in Sui's binary distribution to os version identifiers
# representing VSCode's target platforms used for creating platform-specific plugin distributions
declare -A SUPPORTED_OS
SUPPORTED_OS[macos-arm64]=darwin-arm64
SUPPORTED_OS[macos-x86_64]=darwin-x64
SUPPORTED_OS[ubuntu-x86_64]=linux-x64
SUPPORTED_OS[windows-x86_64]=win32-x64

TMP_DIR=$( mktemp -d -t vscode-create )
trap "clean_tmp_dir $TMP_DIR" EXIT

LANG_SERVER_DIR="language-server"

rm -rf $LANG_SERVER_DIR
mkdir $LANG_SERVER_DIR


BIN_FILES=($BIN_DIR/*.tgz(.))

if (( ${#BIN_FILES[@]} != 4 )); then
echo "Sui binary directory $BIN_DIR should only contain binaries for the four supported platforms"
exit 1
fi


for SUI_ARCHIVE_PATH in "${BIN_FILES[@]}"; do
# Extract just the file name
FILE_NAME=${SUI_ARCHIVE_PATH##*/}
# Remove the .tgz extension
BASE_NAME=${FILE_NAME%.tgz}
# Extract everything untl last `-`
OS_NAME_PREFIX=${BASE_NAME%-*}
# Extract everything after the last `-`
OS_NAME=${OS_NAME_PREFIX##*-}
# Extract everything after the last `-`
OS_VARIANT=${BASE_NAME##*-}

DIST_OS=$OS_NAME-$OS_VARIANT

if [[ ! -v SUPPORTED_OS[$DIST_OS] ]]; then
echo "Found Sui binary archive for a platform that is not supported: $SUI_ARCHIVE_PATH"
echo "Supported platforms:"
for PLATFORM in ${(k)SUPPORTED_OS}; do
echo "\t$PLATFORM"
done
exit 1
fi

rm -rf $TMP_DIR/$DIST_OS
mkdir $TMP_DIR/$DIST_OS
tar -xf $SUI_ARCHIVE_PATH --directory $TMP_DIR/$DIST_OS

# name of the move-analyzer binary
SERVER_BIN="move-analyzer"
ARCHIVE_SERVER_BIN=$SERVER_BIN"-"$DIST_OS
if [[ "$DIST_OS" == *"windows"* ]]; then
SERVER_BIN="$SERVER_BIN".exe
fi

# copy move-analyzer binary to the appropriate location where it's picked up when bundling the
# extension
VSCODE_OS=${SUPPORTED_OS[$DIST_OS]}
vsce "$OP" ${OPTS//VSCODE_OS/$VSCODE_OS} --target "$VSCODE_OS"
done

rm -rf $LANG_SERVER_DIR

# build a "generic" version of the extension that does not bundle the move-analyzer binary
vsce "$OP" ${OPTS//VSCODE_OS/generic}
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,9 @@
"name": "move-trace-debug",
"displayName": "Move Trace Debugger",
"description": "An extension to visualize Move VM traces DAP-style",
"publisher": "mysten",
"icon": "images/move.png",
"license": "Apache-2.0",
"version": "0.0.1",
"preview": true,
"repository": {
Expand Down
Loading