Skip to content

develop.md

Latest commit

 

History

History
143 lines (101 loc) · 4.61 KB

develop.md

File metadata and controls

143 lines (101 loc) · 4.61 KB
Raw

Developing

The easiest way to get started is to open this repository in a GitHub Codespace and everything will be ready for you.

We recommend using Visual Studio Code as it provides excellent support for MakeCode editing, Git, and Codespaces.

Codespaces setup

  • click on Code drop down and select Create Codespace on main
  • you can do your editing from VS Code online or click on Codespaces in lower left and select Open in VS Code to use the desktop version (must be installed on your machine)
  • press "Ctrl + `" to open a terminal and you're ready to go!

In the future, click again on Code to find previously created Codespaces.

Local Install (skip in Codespaces)

  • install Node.js
  • install the MakeCode command line tools (mkc for short)
npm install -g -u makecode
  • clone this repo
git clone https://github.com/microsoft/microcode
  • setup MakeCode project structure (one time only)
cd microcode
mkc init

Build

Note that you can open terminals directly from VS Code by pressing "Ctrl + `".

  • start a compilation server that will automatically compile and reload a compile web version of the editor
mkc serve
mkc build -d

With Jacdac devtools

To load the local editor in a Jacdac devtools page, click on the sim link at the bottom of the local server on http://127.0.0.1:7001. Or,

https://microsoft.github.io/jacdac-docs/clients/javascript/devtools?jacscript=1&simulators=microbitmicrocode#http://127.0.0.1:7001

Creating artwork

If you want to create/edit new sprites, you should import this web site into https://arcade.makecode.com, using the following directions:

  • create 16 x 16 sprite in assets.ts (contains all the artwork for MicroCode)
  • copy the code from the JavaScript view of https://arcade.makecode.com
  • paste code into assets.ts into VS Code
  • make sure it works locally
  • git commit and push

You might also be able to commit and push directly from the web site, but we find that this isn't very reliable.

Updating GitHub pages

To bump and refresh the github pages javascript and pre-built .hex file, run this script

sh ./bump.sh

A GitHub Action will trigger and update the web site within a few minutes.

Overview of implementation

Local files

This little app packs a lot into a small footprint: graphics, UI, editor, compiler, and runtime. Read more...

Dependencies

This app is built with MakeCode Arcade, specifically targeting the NRF52833 MCU of the micro:bit V2 (for now). There are a number of repos containing the C++ of the underlying CODAL runtime:

Build setup for C++ runtime dev

npm install -g pxt-cli
cd pxt-arcade
yarn install
mkdir projects
cd projects
mkdir microcode
cd microcode
export PXT_ASMDEBUG=1
export PXT_COMPILE_SWITCHES=size
export PXT_FORCE_LOCAL=yes
export PXT_NODOCKER=yes
export PXT_RUNTIME_DEV=yes
  • you may use npm instead of yarn
  • you may skip PXT_NODOCKER if you don't have locally installed arm-none-eabi-gcc
  • in projects/microcode create pxt.json file with the following contents:
{
    "additionalFilePath": "../../../microcode",
    "dependencies": {
        "game---light": "file:../../libs/game---light",
        "hw---n3": "file:../../libs/hw---n3",
        "device": "file:../../libs/device",
        "codal-jacdac-pxt": "file:../../../microcode/codal-jacdac-pxt"
    }
}
  • run pxt - it will compile an deploy
  • run code built/codal/libraries/codal-*
  • checkout main or master in all codal-* repos and in jacdac-c

Make sure not to delete projects/microcode/built since it contains your sources. If possible, you can move built/codal/libraries folder somewhere else, and symlink it inside built/codal to avoid accidentally deleting it.