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

feat(docs): update docs #500

Merged
merged 1 commit into from
Jul 3, 2023
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
Expand Up @@ -16,7 +16,7 @@ You can open up this repo just using the badge below. It is recommended to selec
Here is a list of minimal tools you should install to build the Wing repo in your development
environment:

* [Node.js] v18 and [PNPM] v8
* [Node.js] v18 and npm v8
* We recommend [volta] to manage node tools
* [Rust]
* We recommend using [rustup] to manage your Rust installation
Expand All @@ -32,19 +32,19 @@ Installation:
```sh
git clone https://github.com/winglang/wing
cd wing
pnpm install
npm install
```

:::note Nx Commands
[Nx] commands in this document are structured as

```sh
pnpm nx <target> <project>
npx nx <target> <project>
# or
pnpm nx <target> <project> -- <args>
npx nx <target> <project> -- <args>
```

- `pnpm` can be omitted if [Nx] is installed globally
- `npx` can be omitted if [Nx] is installed globally
- `<project>` may be omitted if the current working directory is within the given project directory. If not within any project directory, it will default to the `winglang` CLI project
- If any paths are present in `<args>`, ensure they are either absolute or relative to the project directory

Expand All @@ -57,7 +57,6 @@ pnpm nx <target> <project> -- <args>
[AWS CLI]: https://aws.amazon.com/cli/
[Terraform CLI]: https://learn.hashicorp.com/terraform/getting-started/install.html
[volta]: https://volta.sh
[PNPM]: https://pnpm.io
[Docker]: https://docs.docker.com/get-docker/
[emscripten]: https://emscripten.org/docs/getting_started/downloads.html

Expand All @@ -66,15 +65,15 @@ pnpm nx <target> <project> -- <args>
If you wish to perform a full build (similar to the one CI is running), just run this from the root:

```sh
pnpm build
npm run build
```

It will run the `build`, `test` and `package` targets on all modules.


## 🏠 What's the recommended development workflow?

The `pnpm nx wing` command can be executed from the root of the repository in order to build and run the
The `npx nx wing` command can be executed from the root of the repository in order to build and run the
compiler, SDK (standard library) and the Wing CLI. Nx is configured to make sure only the changed components are built
every time.

Expand All @@ -89,7 +88,7 @@ Now, you can edit a source file anywhere across the stack and run the compiler w
For example:

```sh
pnpm nx wing -- test ../../examples/tests/valid/captures.w
npx nx wing -- test ../../examples/tests/valid/captures.w
```

This command runs the full Wing CLI with the given arguments. Nx will ensure the CLI build is updated.
Expand All @@ -106,12 +105,13 @@ The Wing monorepo uses [Nx] to run commands across all code packages in the `lib
folders. This means it includes packages that form the entire toolchain (compiler, standard library, IDE
extension, etc), and the build and release bind them all together.

Nx will be installed alongside the rest of the project's dependencies after you run `pnpm install`
from the root directory, and can be accessed with `pnpm nx` if [Nx] is not installed globally.
Nx will be installed alongside the rest of the project's dependencies after you run `npm install`
from the root directory, and can be accessed with `npx nx` (it does not need to be installed
separately).

:::note

The first time you run `pnpm install` it may take extra time to install the
The first time you run `npm install` it may take extra time to install the
[wasi-sdk](https://github.com/WebAssembly/wasi-sdk) for you. This is needed to compile Wing for WASM.

If you wish to install it manually, you may do so by running `scripts/setup_wasi.sh`
Expand All @@ -126,7 +126,7 @@ wing](#-how-do-i-build-wing).
To run the tests (and update snapshots), run the following command from anywhere in the monorepo:

```sh
pnpm nx test hangar
npx nx test hangar
```

### Test Meta-Comments
Expand All @@ -153,7 +153,7 @@ This is useful if, for example, the test requires docker. In our CI only linux s
Benchmark files are located in `examples/tests/valid/benchmarks`. To run the benchmarks, run the following command from anywhere in the monorepo:

```sh
pnpm nx bench hangar
npx nx bench hangar
```

Benchmark files should ideally have a meta-comment with the `cases` key. For example:
Expand All @@ -179,21 +179,21 @@ The following command runs the rust tests in wingc, including verification that
It will also make sure to update any snapshots.

```sh
pnpm nx test wingc
npx nx test wingc
```

The following command runs `wingc` on a file. This performs all the compilation steps. Run from the root or `apps/wing`.

```sh
pnpm nx wing -- compile <path to a .w file (full path, or relative to the location of the apps/wing folder)>
npx nx wing -- compile <path to a .w file (full path, or relative to the location of the apps/wing folder)>
```

You can find the compilation artifacts in the apps/wing/targets folder.

To check that your code passes all the lints, run:

```sh
pnpm nx lint wingc
npx nx lint wingc
```

### Optional VSCode extensions for working on the compiler
Expand All @@ -214,22 +214,31 @@ Open the `.w` file you wish to debug compilation for (e.g. `${workspaceFolder}/e
After making changes to `grammar.js`, run:

```sh
pnpm nx build tree-sitter-wing
npx nx build tree-sitter-wing
```

To run the grammar tests (that are located in the `test` folder):

```sh
pnpm nx test tree-sitter-wing
npx nx test tree-sitter-wing
```

To build the grammar as WASM for the web-based playground. Leave off `--docker` if you have emscripten
setup locally:

```sh
npx tree-sitter-cli build-wasm --docker
```

To use the wasm grammar to run a web-based playground where you can explore the AST and test out
highlight queries, run:

```sh
pnpm nx dev tree-sitter-wing
npx tree-sitter-cli playground
```

Make sure to also run `build-wasm` before each time the grammar changes

## 🔨 How do I build the VSCode extension?

The VSCode extension is located in `apps/vscode-wing`. Most of the "logic" is in the language server, which
Expand All @@ -238,13 +247,13 @@ is located in the Wing CLI at `apps/wing/src/commands/lsp.ts`.
To build the extension (also creates an installable `.vsix` file):

```sh
pnpm nx build vscode-wing
npx nx build vscode-wing
```

To run a new isolated VSCode instance with the extension installed:

```sh
pnpm nx dev vscode-wing
npx nx dev vscode-wing
```

To modify the package.json, make sure to edit `.projenrc.ts` and rebuild.
Expand All @@ -256,7 +265,7 @@ Tip: if you want to print debug messages in your code while developing, you shou
To lint Rust code, you can run the `lint` target on the `wingc` or `wingii` projects:

```sh
pnpm nx lint wingc
npx nx lint wingc
```

It's also possible to lint by running `cargo clippy` directly.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -14,9 +14,9 @@ The SDK is built using a couple of extra libraries and tools:

* [CDK for Terraform] ("cdktf") is a framework for defining Terraform infrastructure. The SDK uses it to generate the Terraform files that users deploy.
* [JSII] is a tool we used to compile the SDK. JSII is a wrapper over TypeScript that makes it possible to use the SDK in other languages like Python, Java, C#, and Go. This is made possible through extra type checks. In practice, the main difference from ordinary TypeScript is that you cannot use advanced TypeScript types like `Partial` or generics in public APIs.
* [Projen] is a tool used to manage project configuration files. It uses the `.projenrc.ts` file to generate `package.json` and other files. You can modify it and run `pnpm projen` to regenerate the resources. If you are not touching configuration files, you can totally ignore this.
* [Projen] is a tool used to manage project configuration files. It uses the `.projenrc.ts` file to generate `package.json` and other files. You can modify it and run `npx projen` to regenerate the resources. If you are not touching configuration files, you can totally ignore this.

Everything in the SDK can be built by running `pnpm build` from `libs/wingsdk`. You can also run `pnpm test` to just run tests.
Everything in the SDK can be built by running `npm run build` from `libs/wingsdk`. You can also run `npm run test` to just run tests.

In order to work on the source code, you will need to the build at least once so that TypeScript bindings for Terraform resources will be automatically generated.
These files are not checked in because they are quite large.
Expand All @@ -33,7 +33,7 @@ Check out [this document](https://github.com/winglang/wing/blob/main/libs/wingsd

## 🧱 How do I add a dependency to the SDK?

If you need to add a new npm dependency to the SDK, you can do so by editing the `.projenrc.ts` file and running `pnpm projen` after making the edits.
If you need to add a new npm dependency to the SDK, you can do so by editing the `.projenrc.ts` file and running `npx projen` after making the edits.
If the dependency is a JSII library[2], you should add it to the list named `peerDeps` - otherwise, you should add it to `bundledDeps`.

Here is an example of adding a package named "fast-json-stringify" pinned to major version 5 through the projenrc file:
Expand All @@ -58,8 +58,8 @@ This means that you can generate bindings for any Terraform provider and referen

To add a new provider, go to `libs/wingsdk/.projenrc.ts` and edit the section
that says "CDKTF_BINDINGS" to add the new provider.
Then, run `pnpm projen` to update the project.
One that has finished, you can run `pnpm build` and the new bindings should be generated inside `libs/wingsdk/src/.gen`.
Then, run `npx projen` to update the project.
One that has finished, you can run `npm run build` and the new bindings should be generated inside `libs/wingsdk/src/.gen`.

## 🧩 How do I add a resource to the SDK?

Expand Down Expand Up @@ -100,19 +100,19 @@ All features and bug fixes should have tests! They're easy to forget, but they p
All tests can be run by running the following command from `libs/wingsdk`:

```sh
pnpm test
npm run test
```

During development, you might find it useful to watch for changes and automatically re-run the tests:

```sh
pnpm test:watch
npm run test:watch
```

To re-run individual tests, you can directly use the `vitest` command -- for example:

```sh
pnpm vitest run test/target-tf-aws/bucket.test.ts
npx vitest run test/target-tf-aws/bucket.test.ts
```

## What is the architecture of the Wing SDK?
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ Yes, you can! We use the awesome [Docusaurus](https://docusaurus.io/) project fo
To start the documentation website, run the following command from the root of the repo:

```sh
pnpm docs
npm run docs
```

This magical script will clone the [winglang/docsite](https://github.com/winglang/docsite)
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ keywords: [Wing contributors, contributors, Troubleshooting]

# 🔨 Troubleshooting

## `pnpm build`
## `npm run build`

#### Mac dev tools: `error: linking with cc failed: exit code: 1`
Make sure to install Mac dev tools:
Expand All @@ -16,11 +16,11 @@ xcode-select --install

#### NPM registry: `npm ERR! Cannot read properties of null (reading 'pickAlgorithm')`
```sh
pnpm store prune
pnpm config set registry https://registry.npmjs.org/
npm cache clear --force
npm config set registry https://registry.npmjs.org/
```

## `pnpm test`
## `npm run test`

`Error: Failed to bundle function: assertion failed [block != nullptr]: BasicBlock requested for unrecognized address (BuilderBase.h:550 block_for_offset)`

Expand All @@ -41,7 +41,7 @@ Check the installed node runtime architecture:
node -e 'console.log(process.arch)'
> arm64
```
Your previously installed `esbuild/darwin-x64` package needs to be replaced by `esbuild/darwin-arm64`. Therefore, remove `esbuild` folder from `./libs/wing/wingsdk/node_modules` and run `pnpm install`.
Your previously installed `esbuild/darwin-x64` package needs to be replaced by `esbuild/darwin-arm64`. Therefore, remove `esbuild` folder from `./libs/wing/wingsdk/node_modules` and run `npm install`.

## `This version of rustfmt is deprecated. Use rustfmt-nightly.`

Expand Down