Skip to main content

Contributing

Contributions are welcome! DeviceScript takes pull requests.

Contributions​

We have a few guides to help with specific contributions.

Samples​

Documentation samples are located under website/docs/samples. Each .mdx file contains a single self-contained sample.

It is typically easiest to develop a sample in a dedicate .ts file to leverage the editor's features, and then copy it to the .mdx file.

To run the docs locally, run yarn docs. This will launch the docusaurus development server and refresh the documentation page on each edit.

If your sample requires multiple files, such as images,

  • create a folder with the same name as the .mdx file
  • move your .mdx file and rename it to index.mdx
  • add a _category_.json file with the front matter
{
    "label": "Samples",
    "position": 3
}

Local development​

The development requirement will vary (widely) depending on which part of DeviceScript you want to work on.

Using Visual Studio Code is strongly recommended.

Repository structure​

This repository contains:

  • jacdac-c submodule, including sources for Jacdac client libraries and DeviceScript VM
  • compiler/ - sources for DeviceScript compiler
  • runtime/devicescript-vm/ - glue files to build DeviceScript VM as WASM module using emscripten; vm/dist/ contain pre-built files
  • packages - builtin packages and sample project (packages/sampleprj)
  • runtime/posix/ - implementation of Jacdac SDK HAL for grown-up POSIX-like operating systems (as opposed to embedded platforms)
  • vscode - Visual Studio Code extension
  • website - docusaurus documentation side

Compiler, runtime and command line​

You can use the devcontainer to build. The instructions are tested for a Unix terminal.

If you want to build locally you need to install node.js. After cloning, the repo run

yarn setup

To run a watch build and the docs, run

nvm use 18
yarn dev
  • start jacdac devtools (the npm version) and let it run
  • open this folder in VSCode; use "Reopen in Container" if needed
  • start Terminal in VSCode
  • run yarn install
  • run yarn build
  • run yarn devs run devs/samples/something.ts - this will execute given DeviceScript program using the WASM binary

If you want to develop the runtime (as opposed to compiler or website), you will also need GNU Make, C compiler, and emscripten. Once you have it all:

  • run make native to compile using native C compiler
  • run yarn devs crun devs/samples/something.ts - this will execute given DeviceScript program using the POSIX/native binary
  • run ./runtime/built/jdcli 8082 - this will run the POSIX/native DeviceScript server, which can be accessed from the devtools dashboard
  • run make em to compile using emscripten

To lint sources,

  • run yarn lint

Visual Studio Extension​

Open the Debug view in VSCode and run the VSCode Extension configuration. This will launch a new VSCode instance with the extension loaded. A build is automatically triggered before launch VSCode.

Building packages​

Similar to working on the Visual Studio Code extension, lunch the VSCode Extension debugger configuration. This will launch a new VSCode instance with the extension loaded. It should also open the packages folder which will allow you to work on the built-in packages.

Documentation​

Run yarn docs and edit any markdown file in the website/docs folder. The changes should be automatically picked up and rendered by docusaurus.

Add Core JavaScript APIs​

The DeviceScript core js library is not complete; but it is possible to fill the gaps as needed. The requests are tracked by the core js issue label.

You will need a local development setup for these tasks.

If you want to add a new function:

  • find the corresponding function definition in one of the lib/es....d.ts file.
  • copy the definition in the corresponding interface in packages/core/src/corelib.d.ts
  • implement the function in the implementation file of the type (see packages/core/src/array.ts for example). If you are adding a new file, make sure to import it in packages/core/src/index.ts.
  • add test cases in the corresponding test file under devs/run-tests
  • build and test
  • create a pull request and go!

If you want to add a new Type, we currently have a limitation with the core package and you will need to add it to the runtime package:s

  • implement the class in the implementation file of the type (see packages/runtime/src/map.ts for example). If you are adding a new file, make sure to import it in packages/runtime/src/map.ts.
  • add test cases in the corresponding test file under packages/runtime/src/main.ts
  • build and test
  • create a pull request and go!

Documenting/patching console output​

To add new substitions from console output message to pretty text + URL, do the following.

The website/docs/developer/errors.mdx gets parsed by builderrors.mjs. The hash of the H2 titles is the console log look up key (replacing - with spaces) and the H2 text will replace that key + URL.

loopback rx ovf --> Loopback buffer overflow (....#loopback-rx-ovf)

Adding Builtin Packages​

Adding a new package is more advanced scenario and most likely we should have a discussion prior to start this work. You are welcome to publish packages under your account in npm.

A good question to start with: Do we need a new builtin package or should it be a new npm package?

Generally, search for @devicescript/gpio within the workspace. The main places that need updating is:

  • this file, website/docs/developer/packages.mdx
  • list in plugin/src/plugin.ts
  • list in devs/run-test/allcompile.ts

After adding a new packages, run yarn at the top-level to update workspace links, followed by the usual yarn build.

Release process​

Run yarn bump (or make bump). Alternatively, edit img_version_patch in bytecode/bytecode.md and push.

The cloud build will rebuild and check-in the VM, update version numbers in all package.json files, and publish them.

If you bump minor, you need to also bump the firmware repos:

make bump

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.