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.
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
The command line tool can be invoked as makecode
or mkc
for short.
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!
This command downloads the sources of extensions to the file system so that your TypeScript IDE can use them
mkc install
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
Use --watch
, or -w
, with mkc build
to automatically watch changes in source files and rebuild automatically.
mkc -w
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=...
.
To access the build files from a remote machine,
built
folderDownload
on the desired file.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
Run the clean command to erase build artifacts and cached packages.
mkc clean
Search for extensions hosted on GitHub.
mkc search jacdac
You can use the result with the add
command to add extensions to your project.
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
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
Downloads a shared MakeCode project to files and initializes the project.
mkc download https://.....
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.
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)--hw help
command line option to list variantspxt.json
You can use --config-path
or -c
to build for a different configuration.
mkc -c mkc-arcade.json
This section describes how to build mkc itself.
mkc is split into three packages:
npm install makecode
)npm install
from the root of this repo (this will also link the local packages)cd packages/makecode-core && npm run watch
cd packages/makecode-node && npm run watch
node path/to/pxt-mkc/packages/makecode-node/makecode
in your project folderIf 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.
To release a package, run the following script to create+push a tagged release:
node ./scripts/release.js bump makecode-core
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.