microsoft / pxt-mkc

Command line tool for MakeCode editors

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

Do not install the npm mkc package, it is another package.

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 install

This command downloads the sources of extensions to the file system so that your TypeScript IDE can use them

mkc install

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 build compile switches

Options can be passed to PXT compiler using --compile-flags (-f) option:

mkc -f size            # generate .csv file with function sizes
mkc -f asmdebug        # generate more comments in assembly listing
mkc -f profile         # enable profiling counters
mkc -f rawELF          # don't generate .UF2 but a raw ELF file
mkc -f size,asmdebug   # example with two options

The same options (except for asmdebug) can be passed to website with ?compiler=... or ?compile=... argument and to the regular pxt command line utility with PXT_COMPILE_SWITCHES=....

Built files in containers, GitHub Codespace, ...

To access the build files from a remote machine,

• open Visual Studio Code
• browse to the built folder
• right click Download on the desired file.

mkc serve

Use mkc serve to start a watch-build and localhost server with simulator. Defaults to http://127.0.0.1:7001

mkc serve

You can change the port using port.

mkc serve --port 7002

By default, the simulator ignores loader.js. If you have modifications in that file, use --force-local to use your loader.js.

mkc serve --force-local

mkc clean

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

mkc clean

mkc search

Search for extensions hosted on GitHub.

mkc search jacdac

You can use the result with the add command to add extensions to your project.

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 all nested projects in a mono-repo.

mkc bump

Use --major, --minor, --patch to automatically increment the version number.

mkc bump --patch

Adding --version-file will make mkc write a TypeScript file with the version number.

mkc bump --version-file version.ts

Add --stage to test the bump without pushing to git.

mkc bump --stage

mkc download

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

mkc download https://.....

Advanced 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 or -c to build for a different configuration.

mkc -c mkc-arcade.json

Local development

This section describes how to build mkc itself.

mkc is split into three packages:

1. makecode-core - which contains most of the functionality/shared code
2. makecode-node - which contains the node CLI (this is the package that is installed via npm install makecode)
3. makecode-browser - which contains a browser implementation of the mkc language service

Building

• install node.js
• run yarn install from the root of this repo (this will also link the local packages)
• start the build watch in makecode-core and makecode-node:
  • (run these in separate terminals)
  • cd packages/makecode-core && yarn watch
  • cd packages/makecode-node && yarn watch
• run node path/to/pxt-mkc/packages/makecode-node/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 [email protected] with any additional questions or comments.

pxt-mkc's Issues

update dependencies commands

serve sounds, images

It's a bit limiting that the local dev server does not serve images/sounds.

Support for deploy command

Support for --deploy DRIVE_NAME to automatically copy .hex/.uf2 file to drive.

add command to bust the global editor cache

Maybe part of the "clean" command?

use etag to check if binary.js was modified

The current scheme is heavy on network when working from a codespace.

use supportedTarget to determine possible mkc

in pxt.json, "supportedTargets": ["microbit"]

After bump, ping cloud to refresh caches

In the client we do,

            await pxt.github.listRefsAsync(parsed.slug, "tags", true, true);

command line downloads github extension on every build

it should be cached

node cli broken

Support for buildiong from nest repo

Trying to build from a sub-folder in pxt-jacdac.

/pxt-jacdac/button (master)
$ mkc
(node:10300) UnhandledPromiseRejectionWarning: Error: ENOENT: no such file or directory, open 'mkc.json'
    at Object.openSync (fs.js:458:3)
    at Object.readFileSync (fs.js:360:35)
    at C:\Users\jhalleux\AppData\Roaming\npm\node_modules\makecode\built\cli.js:72:43
    at Generator.next (<anonymous>)
    at C:\Users\jhalleux\AppData\Roaming\npm\node_modules\makecode\built\cli.js:8:71
    at new Promise (<anonymous>)
    at __awaiter (C:\Users\jhalleux\AppData\Roaming\npm\node_modules\makecode\built\cli.js:4:12)
    at mainCli (C:\Users\jhalleux\AppData\Roaming\npm\node_modules\makecode\built\cli.js:51:12)
    at Object.<anonymous> (C:\Users\jhalleux\AppData\Roaming\npm\node_modules\makecode\built\cli.js:146:1)
    at Module._compile (internal/modules/cjs/loader.js:1133:30)

use makecode.com/editors.json instaed

pxt-mkc/src/loader.ts

Line 13 in 742dd1b

export const descriptors: TargetDescriptor[] = [{

support recursive bump

C++ build?

makecode failing (microcode build)

Run makecode --java-script
node:internal/modules/cjs/loader:998
  throw err;
  ^

Error: Cannot find module '../../makecode-core/built/commands'
Require stack:
- /opt/hostedtoolcache/node/16.19.0/x6[4](https://github.com/microsoft/microcode/actions/runs/4180400738/jobs/7241342595#step:6:5)/lib/node_modules/makecode/built/cli.js
- /opt/hostedtoolcache/node/16.19.0/x64/lib/node_modules/makecode/makecode
    at Function.Module._resolveFilename (node:internal/modules/cjs/loader:99[5](https://github.com/microsoft/microcode/actions/runs/4180400738/jobs/7241342595#step:6:6):15)
    at Function.Module._load (node:internal/modules/cjs/loader:841:27)
    at Module.require (node:internal/modules/cjs/loader:10[6](https://github.com/microsoft/microcode/actions/runs/4180400738/jobs/7241342595#step:6:7)[7](https://github.com/microsoft/microcode/actions/runs/4180400738/jobs/7241342595#step:6:8):19)
    at require (node:internal/modules/cjs/helpers:103:1[8](https://github.com/microsoft/microcode/actions/runs/4180400738/jobs/7241342595#step:6:9))
    at Object.<anonymous> (/opt/hostedtoolcache/node/16.1[9](https://github.com/microsoft/microcode/actions/runs/4180400738/jobs/7241342595#step:6:10).0/x64/lib/node_modules/makecode/built/cli.js:16:20)
    at Module._compile (node:internal/modules/cjs/loader:1165:14)
    at Object.Module._extensions..js (node:internal/modules/cjs/loader:1219:[10](https://github.com/microsoft/microcode/actions/runs/4180400738/jobs/7241342595#step:6:11))
    at Module.load (node:internal/modules/cjs/loader:1043:32)
    at Function.Module._load (node:internal/modules/cjs/loader:878:[12](https://github.com/microsoft/microcode/actions/runs/4180400738/jobs/7241342595#step:6:13))
    at Module.require (node:internal/modules/cjs/loader:1067:19) {
  code: 'MODULE_NOT_FOUND',
  requireStack: [
    '/opt/hostedtoolcache/node/[16](https://github.com/microsoft/microcode/actions/runs/4180400738/jobs/7241342595#step:6:17).[19](https://github.com/microsoft/microcode/actions/runs/4180400738/jobs/7241342595#step:6:20).0/x64/lib/node_modules/makecode/built/cli.js',
    '/opt/hostedtoolcache/node/16.19.0/x64/lib/node_modules/makecode/makecode'
  ]
}
Error: Process completed with exit code 1.

template command to generate empty project

search for built in packages

we never update editor without -u

Once the editor is downloaded we never update it again (unless -u option is specified). Maybe we should say, once per day?

CC @pelikhan

don't build nested pxt_modules

the cli goes into pxt_modules and tries to build those

Populate pxt.json with target info

Like the online editor

fix tsconfig.json template?

drop pxt-modules on every build

add dependency command

Add depenencies, update dependencies commands.

User won't get the formatting right.

MKC Does Not Re-Read mkc.Json After the First Time

Problem

The Project class in mkc.ts will not re-read mkc.json after it loads the first time. Even if the targetwebsite changes, it'll still build with the old version.

Repro

To repro do the following:

• In an empty folder run mkc init arcade
• Change targetWebsite iin mkc.json to https://arcade.makecode.com/v1.12.22
• Run mkc build -j -w to build and start a watch
• Notice the build runs with v1.12.22
• Change the patch version in mkc.json to 23
• Notice the build runs with v1.12.22 again

You can keep changing the version and it will never change.

Notes

Start looking at loadPkgAsync for a possible solution.

pxt-mkc/packages/makecode-core/src/mkc.ts

Lines 201 to 204 in b20c170

	async loadPkgAsync() {
	if (this.mainPkg) return
	const prj = await this.readPackageAsync()

honor supportedTargets in pxt.json

Ignore if missing, otherwise must be part of the list

Add -r as alias for mono-repo

clean command

Command to remove built, pxt_modules folders

watch command

add support for maker

option to start simulator in watch mode

Interdependencies in mono repo

When reference another mono-repo nested project, we download it from the github instead of using a local path.

Use update-notifier

To notify users a new version of the cli is available.

can not specify local directory for extensions

mkc init microbit ../my-pxt-jacdac gives the following output:

initializing project for micro:bit
saving main.ts
saving pxt.json
saving tsconfig.json
saving .prettierrc
saving .github/workflows/makecode.yml
using project: /Users/andrew/mkctest/pxt.json
using config: /Users/andrew/mkctest/mkc.json
using editor: https://makecode.microbit.org/beta v5.1.5
resolution of ../my-pxt-jacdac failed (404)

Ok, so let's try with file://, which errors out because it doesn't understand that URI:

unkown repository format, try https://github.com/.../...

Ok, try mkc add -- same results with these two different methods.

If I run the init without the extension, I can add the local directory just fine by editing mkc.json as outlined at https://microsoft.github.io/pxt-mkc/.

It seems that this should be doable from the mkc init and mkc add command lines.

Bump should create a github release

To match what the web client does. We can use the github CLI to do this.

bump should pull first

links instructions is ignored

mkc ignore include instruction that allows to override dependencies with local packages.

Here is an example: https://github.com/microsoft/pxt-jacdac/blob/master/mkc.json#L7

If you build pxt-jacdac/packages/servo for example, it should not download pxt-jacdac from github, but use the local package as defined in https://github.com/microsoft/pxt-jacdac/blob/master/links.json

--bump should add a new line at the end of pxt.json

The makecode editor always pads pxt.json with a new line. We should mimic this.

failed add suggestion

use search to suggest missing packages

serve should use local sim files if avilable

If index.html, and other files under assets are available, mkc should use those in mkc serve

allow updating `shims.d.ts`/`enums.d.ts`

support compiling in JSON as resource

It would be great to be able to better handle JSON resources (like loc strings) through mkc

• convert .json files into TS dictionary
• select specific .ts file based on CLI flag

Goal is to compile locale specfic hex files for microcode.

The automated release is failing 🚨

🚨 The automated release from the master branch failed. 🚨

I recommend you give this issue a high priority, so other packages depending on you could benefit from your bug fixes and new features.

You can find below the list of errors reported by semantic-release. Each one of them has to be resolved in order to automatically publish your package. I’m sure you can resolve this 💪.

Errors are usually caused by a misconfiguration or an authentication problem. With each error reported below you will find explanation and guidance to help you to resolve it.

Once all the errors are resolved, semantic-release will release your package the next time you push a commit to the master branch. You can also manually restart the failed CI job that runs semantic-release.

If you are not sure how to resolve this, here is some links that can help you:

• Usage documentation
• Frequently Asked Questions
• Support channels

If those don’t help, or if this issue is reporting something you think isn’t right, you can always ask the humans behind semantic-release.

---

No npm token specified.

An npm token must be created and set in the NPM_TOKEN environment variable on your CI environment.

Please make sure to create an npm token and to set it in the NPM_TOKEN environment variable on your CI environment. The token must allow to publish to the registry https://registry.npmjs.org/.

---

Good luck with your project ✨

Your semantic-release bot 📦🚀

Docs are outdated

A few options were added to the cli but not documented.

use commands for commands...

Commander support commands, lets use them.

https://www.npmjs.com/package/commander#user-content-commands

bump command never finishes

does not fail build when process crashes

mono repo search

Not supported by the cloud yet

Error don't fail the build

When mkc fails, it should return an error code so that the build fails.

Add local dev/test instructions

mono-repo install

Support for mono repo

• GIthub name resolution does not handle nested packages
• recurse builds