MKC - command line tool for MakeCode editors

This package includes a tool that can compile MakeCode (PXT) projects by downloading parts of a released MakeCode web app and running them in node.js.

This is different than pxt command line tool, which is used primarily during development of MakeCode editors.

Installation

Make sure to install node.js.

To install mkc globally, run

npm install -g makecode

To update mkc,

npm install -u -g makecode

Usage

The command line tool can be invoked as makecode or mkc for short.

mkc init

To start a new micro:bit project in an empty folder:

mkc init microbit

where microbit is the template name. To get the list of supported templates, do mkc help init.

It is possible to specify a list of dependencies to be added to the template.

mkc init microbit jacdac jacdac-button jacdac-led

Your project is ready to be edited. If you are a Visual Studio Code user, type code . and you're ready to go!

mkc build

In a folder with pxt.json file, run the build command.

mkc build

Build is also the default command, so you can just leave it out.

mkc

You can also pass --hw f4, --hw d5 etc. Try --hw help to get a list. Use mkc -j to build JavaScript (it defaults to native).

To build and deploy to a device add -d.

mkc -d

The tool checks once a day if the MakeCode editor has been updated. However, you can force an update by using --update during a build.

mkc --update

mkc build --watch

Use --watch, or -w, with mkc build to automatically watch changes in source files and rebuild automatically.

mkc -w

mkc clean

Run the clean command to erase build artifacts and cached packages.

mkc clean

mkc add

Adds a new dependency to the project. Pass a GitHub repository URL to the add command.

mkc add https://github.com/microsoft/pxt-jacdac/button

For Jacdac extensions, simply write jacdac-servicename

mkc add jacdac-button

mkc bump

Interactive update of the version number of the current project and nested projects in a mono-repo.

mkc bump

mkc download

Downloads a shared MakeCode project to files and initializes the project.

mkc download https://.....

Configuration

The init commands creates a mkc.json file that you can also use for additional configurations.

{
  "targetWebsite": "https://arcade.makecode.com/beta",
  "hwVariant": "samd51",
  "links": {
    "jacdac": "../../pxt-jacdac"
  },
  "overrides": {
    "testDependencies": {}
  },
  "include": ["../../common-mkc.json"]
}

All fields are optional.

• targetWebsite says where to take the compiler from; if you omit it, it will be guessed based on packages used by pxt.json; you can point this to a live or beta version of the editor, as well as to a specific version (including SHA-indexed uploads generated during PXT target builds)
• hwVariant specifies default hardware variant (currently only used in Arcade); try --hw help command line option to list variants
• links overrides specific packages; these can be github packages or built-in packages
• overrides is used to override specific keys in pxt.json
• files listed in include are merged with the keys from the later ones overriding the keys from the earlier ones; the keys from the current file override all included keys

You can use --config-path to build for a different configuration

mkc -c mkc-arcade.json

Local development

This section describes how to build mkc itself.

• install node.js
• run yarn install
• start the build: yarn watch
• run node path/to/pxt-mkc/makecode in your project folder

If you want to test out changes in pxt, first run the build as usual, and then replace $HOME/.pxt/mkc-cache/https_58__47__47_<your-editor>-pxtworker.js with pxt/built/web/pxtworker.js. Make sure to run makecode tool without the -u option.

Releases

A new release will be automatically generated by the build system based on these commit naming guidelines.

• feat: A new feature
• fix: A bug fix
• docs: Documentation only changes style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
• refactor: A code change that neither fixes a bug nor adds a feature
• perf: A code change that improves performance
• test: Adding missing or correcting existing tests
• chore: Changes to the build process or auxiliary tools and libraries such as documentation generation

Contributing

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.