From 2482abf9f87d83bd99e6a1eeabf233ed2c04f873 Mon Sep 17 00:00:00 2001 From: Franklin Tse Date: Fri, 31 Aug 2018 04:39:43 +0800 Subject: [PATCH] V1 Readme (#1144) * Update README * Further refine readme * Further update * Correct the build badge * Remove link to cloning a repository * Add back npm run build * localbuild flag * Fix the header --- README.md | 58 +++++++++++++++++++++---------------------------------- 1 file changed, 22 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index 3ab11e23..19bf3cd8 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,12 @@ # micro:bit target for PXT -This target allows you to program a [BBC micro:bit](https://microbit.org/) using -PXT ([Microsoft Programming Experience Toolkit](https://github.com/Microsoft/pxt)). +[![Build Status](https://travis-ci.org/Microsoft/pxt-microbit.svg?branch=v1)](https://travis-ci.org/Microsoft/pxt-microbit) -* [Try it live](https://makecode.microbit.org) +*This README is for pxt-microbit v1.x, which is [currently in beta](https://makecode.com/blog/microbit/v1-beta).* -[![Build Status](https://travis-ci.org/Microsoft/pxt-microbit.svg?branch=master)](https://travis-ci.org/Microsoft/pxt-microbit) +pxt-microbit is a [Microsoft Programming Experience Toolkit (PXT)](https://github.com/Microsoft/pxt) target that allows you to program a [BBC micro:bit](https://microbit.org/). pxt-microbit v1.x requires pxt v3.x, which is currently in the [master branch of pxt](https://github.com/Microsoft/pxt/tree/master). + +* [Try it live](https://makecode.microbit.org/beta) ## Issue tracking @@ -15,50 +16,35 @@ Please add an issue if you discover an (unreported) bug. The local server lets you to run the editor and serve the documentation from your own computer. -### Setup -This section explains how to setup your development environment for pxt-microbit, whether that be to run a copy locally or to make source changes. -Note that pxt-microbit can not be run without its main dependancy, [pxt](https://github.com/Microsoft/pxt). Below explains how to setup both. +### Setup -The following commands perform a one-time setup after synching the repo on your machine. -* Note for any editing of the `.cpp` files, Yotta must be installed. To do so, follow the instructions on [their site](http://docs.yottabuild.org/). -* Install node.js 8.9.4 or higher. -* Install requirements for [pxt](https://github.com/Microsoft/pxt). Note the v0 branch must be used for pxt-microbit (add ``sudo`` for Mac/Linux shells). -``` -npm install -g jake -npm install -g typings -``` - -* [Clone the pxt repository](https://help.github.com/articles/cloning-a-repository/) and set it to the v0 branch. +1. Install [Node.js](https://nodejs.org/) 8.9.4 or higher. +2. Install [Yotta](http://docs.yottabuild.org/) if you are going to edit any `.cpp` files. +3. Clone the pxt repository. ``` git clone https://github.com/microsoft/pxt cd pxt -git checkout v0 ``` - -* Install the pxt dependencies. +4. Install the dependencies of pxt and build it ``` npm install -typings install -jake -cd ../ +npm run build +cd .. ``` - -* [Clone this repo](https://help.github.com/articles/cloning-a-repository/) to your computer. +5. Clone the `v1` branch of this repository. ``` -git clone https://github.com/microsoft/pxt-microbit +git clone https://github.com/microsoft/pxt-microbit --branch v1 cd pxt-microbit ``` -* install the PXT command line (add ``sudo`` for Mac/Linux shells). +6. Install the PXT command line (add `sudo` for Mac/Linux shells). ``` npm install -g pxt ``` -* install the dependencies +7. Install the pxt-microbit dependencies. ``` npm install - ``` - -* Link pxt-microbit back to base pxt repo. +8. Link pxt-microbit back to base pxt repo (add `sudo` for Mac/Linux shells). ``` npm link ../pxt ``` @@ -73,21 +59,21 @@ Note the above command assumes the folder structure of ### Running -Run this command from inside pxt-microbit to open a local web server (add ``sudo`` for Mac/Linux shells) +Run this command from inside pxt-microbit to open a local web server ``` -pxt serve --cloud +pxt serve ``` If the local server opens in the wrong browser, make sure to copy the URL containing the local token. Otherwise, the editor will not be able to load the projects. -If you need modify the `.cpp` files (and have installed yotta), enable yotta compilation by removing the ```--cloud``` flag (add ``sudo`` for Mac/Linux shells): +If you need to modify the `.cpp` files (and have installed yotta), enable yotta compilation using the `--localbuild` flag: ``` -pxt serve +pxt serve --localbuild ``` ### Updates -To update your PXT version and make sure you're running the latest tools, run (add ``sudo`` for Mac/Linux shells): +To update your PXT version and make sure you're running the latest tools, run: ``` pxt update ```