From 6099d7f34fe8553a2e696706dee984b526918cb4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bastian=20M=C3=BCller?= Date: Mon, 25 Mar 2024 14:10:13 -0700 Subject: [PATCH 1/2] document how to analyze code and values --- docs/FAQ.md | 31 +++++++++++++++++++++++++++++-- 1 file changed, 29 insertions(+), 2 deletions(-) diff --git a/docs/FAQ.md b/docs/FAQ.md index b643c8f613..59c80927a9 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -20,6 +20,33 @@ For example, a simple integer literal would be "boxed" in several outer grammar ## What is the algorithmic efficiency of operations on arrays and dictionaries? -Arrays and dictionaries are implemented [as trees](https://github.com/onflow/atree). -This means that lookup operations do not run in constant time. +Arrays and dictionaries are implemented [as trees](https://github.com/onflow/atree). +This means that lookup operations do not run in constant time. In certain cases, a mutation operation may cause a rebalancing of the tree. + +## Analyzing Cadence code + +To analyze Cadence code, you can use the [Go package `github.com/onflow/cadence/analysis`](https://github.com/onflow/cadence/tree/master/tools/analysis). +It is similar to the [Go package `golang.org/x/tools/go/analysis`](https://pkg.go.dev/golang.org/x/tools/go/analysis), which allows analyzing Go code. +The blog post at https://eli.thegreenplace.net/2020/writing-multi-package-analysis-tools-for-go/ can be followed to learn more about how to write an analyzer. +The API of the analysis package for Cadence programs is fairly similar to the package for Go programs, but not identical. + +To run the analyzer pass, the [Cadence linter tool](https://github.com/onflow/cadence-tools/tree/master/lint#cadence-lint) can be used. +For example, it allows running the pass over all contracts of a network. + +There are several options to run the analyzer pass with the linter tool: +- The analysis pass can be written directly in the linter tool. See the existing passes in the linter tool for examples. +- The analysis pass can be written in a separate package in Cadence, and the linter tool can use it. + The go.mod `replace` statement can be used to point to a locally modified Cadence working directory. +- The linter supports [Go plugins](https://pkg.go.dev/plugin) (see e.g. https://eli.thegreenplace.net/2021/plugins-in-go/) https://github.com/onflow/cadence-tools/blob/83eb7d4d19ddf2dd7ad3fdcc6aa6451a6bc126ff/lint/cmd/lint/main.go#L48. + The analyzer pass can be written in a separate module, built as a plugin, and loaded in the linter using the `-plugin` command line option. + +## Analyzing Cadence values / state snapshots + +To analyze Cadence values (`interpreter.Value`), you can use the function [`interpreter.InspectValue`](https://github.com/onflow/cadence/blob/master/runtime/interpreter/inspect.go#L31). + +To find static types in Cadence values (e.g. in type values, containers, capabilities), you can see which values contain static types in the [Cadence 1.0 static type migration code](https://github.com/onflow/cadence/blob/master/migrations/statictypes/statictype_migration.go#L67). + +To load values from a state snapshot you can use the [flow-go `util` commad](https://github.com/onflow/flow-go/tree/master/cmd/util) to convert a state snapshot in trie format to a file which just contains the payloads. + +To get a `runtime.Storage` instance from it, use `util.ReadPayloadFile`, `util.NewPayloadSnapshot`, `state.NewTransactionState`, `environment.NewAccounts`, `util.NewAccountsAtreeLedger`, and finally `runtime.NewStorage`. From 7400ca146c66d61c8b241f2b4dcca62d11fea8f3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bastian=20M=C3=BCller?= Date: Mon, 25 Mar 2024 14:10:24 -0700 Subject: [PATCH 2/2] fix documentation --- docs/README.md | 4 ++-- docs/development.md | 24 ------------------------ docs/syntax-highlighting.md | 2 +- 3 files changed, 3 insertions(+), 27 deletions(-) diff --git a/docs/README.md b/docs/README.md index 179ef09118..6037e52c7d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,7 +1,7 @@ # Documentation -This directory documention for contributors to/developers of Cadence. +This directory contains documentation for contributors to/developers of Cadence. -If you are looking for documentation for Cadence, it can be found at https://cadence-lang.org/. +If you are looking for documentation for using Cadence, it can be found at https://cadence-lang.org/. The source for the user documentation is at https://github.com/onflow/cadence-lang.org, not in this repository. diff --git a/docs/development.md b/docs/development.md index fd8ab99c76..77544d51ab 100644 --- a/docs/development.md +++ b/docs/development.md @@ -1,29 +1,5 @@ # Development -## Running the latest version of the Language Server in the Visual Studio Code Extension - -- Ensure that a `replace` statement exists in `languageserver/go.mod`, so that the language server compiles with the local changes to Cadence. - -- Find the Visual Studio Code preference named "Cadence: Flow Command" and change it to: - - ```text - /path/to/cadence/languageserver/run.sh - ``` - -- Restart Visual Studio Code - -This will automatically recompile the language server every time it is started. - -## Debugging the Language Server - -- Follow the instructions above (see "Running the latest version of the Language Server in the Visual Studio Code Extension") - -- Attach to the process of the language server started by Visual Studio Code. - - For example, in Goland, choose Run -> Attach to Process. - - This requires gops to be installed, which can be done using `go get github.com/google/gops`. - ## Tools The [`runtime/cmd` directory](https://github.com/onflow/cadence/tree/master/runtime/cmd) diff --git a/docs/syntax-highlighting.md b/docs/syntax-highlighting.md index 01f6589594..1df8cf8f1a 100644 --- a/docs/syntax-highlighting.md +++ b/docs/syntax-highlighting.md @@ -1,7 +1,7 @@ # Syntax Highlighting Cadence There are currently several options to highlight Cadence code. -Currently those options are integrated into the projects they are used in, but they could be extracted and made generally useable (please let us know e.g. by creating a feature request issue). +Currently, those options are integrated into the projects they are used in, but they could be extracted and made generally useable (please let us know e.g. by creating a feature request issue). ## HTML output