sksum / musicblocks-2

A complete overhaul of the original Music Blocks

Music Blocks 2

A complete overhaul of the original Music Blocks.

Notes

Please visit the discussions tab at the top of the repository to follow the planning progress.

Setup Development Environment

This project is containerized using docker. Therefore, it requires docker to be installed on the development machine.

1. Setup docker.

   • For Linux, install Docker Engine.
   • For Windows or Mac (x86_64 / amd64), install Docker Desktop.

2. Open a teminal and navigate to working directory (where the source code will reside).

3. Git Clone (additional installation of Git required on Windows) this repository using

   git clone https://github.com/sugarlabs/musicblocks-2.git

4. Build docker image and launch docker network.

   Note: A built initial development image has been published to Sugar Labs GitHub Container Registry (GHCR) , which can be pulled directly, so you don't have to build it again. Pull using

   docker pull ghcr.io/sugarlabs/musicblocks:initial

   Nagivate inside the project directory and launch the docker network using

   docker-compose up -d

   If you haven't pulled the image from the GitHub Container Registry (GHCR), it'll first build the image using the Dockerfile, then launch the docker network. If an image already exists locally, it'll not be rebuilt. To force a rebuild from the Dockerfile before launching the docker network, add the --build flag.

5. In another terminal, run

   docker attach musicblocks

6. The Linux Debian 10.7 (buster) shell in the docker container named musicblocks is spawned and standard input/output is connected to the terminal.

   Node (Node.js Runtime), npm (Node Package Manager), tsc (TypeScript Compiler), and Dart-SDK (Dart - Software Development Kit) should be installed. Check using

   node --version && npm --version && tsc --version && dart --version

   Output should look like

   v14.15.1
   6.14.8
   Version 4.1.3
   Dart SDK version: 2.10.4 (stable) (Unknown timestamp) on "linux_x64"

7. To shut down the docker network, run (in the terminal where you ran docker-compose up -d)

   docker-compose down

8. To install all the dependencies (in package.json), run

   npm ci

9. To spawn a HTTP Server (uses Python 3's http.server), run

   npm run serve

   This is spawned on 0.0.0.0:80 inside the container, but mapped to localhost:5001 on host. Visit localhost:5001 in a browser to view the webpage served.

10. Run React scripts.

    • For unoptimized development serving, run

      npm start

      This is spawned on 127.0.0.1:3000 inside the container, but mapped to localhost:5000 on host. Visit localhost:5000 in a browser to view the webpage served.

    • For testing, run

      npm run test

    • For generating a production build, run

      npm run build

    Note: If you're running using Docker Desktop on Windows or Mac, you might experience longer execution times for these scripts. This happens due to cross-file-system communication. Duration varies across machines; duration primarily depends on hard drive read/write speed.

11. Miscellaneous commands.

    • To launch the Node runtime, run

      node

    • To run a JavaScript file, say file.js, run

      node file.js

    • To transpile a TypeScipt file, say file.ts, to JavaScript, run

      tsc file.ts

      This transpilation produces file.js.

    • To run a Dart file, say file.dart, run

      dart file.dart

    • To compile a Dart file, say file.dart, to JavaScript, run

      dart compile js -o file.js file.dart

      This compilation produces file.js, file.js.deps, and file.js.map.

Editor

All code is just plain text, so it doesn't really matter what you use to edit them. However, using modern, feature-rich IDEs/text-editors like Atom, Brackets, WebStorm, Sublime Text, Visual Studio Code, etc. makes life way easier. These come with a directory-tree explorer, and an integrated terminal, at the very least, while having support for plugins/extensions to expand their functionality.

Some (non-exhaustive) benefits of using these are syntax highlighting, warning/error annotations, formatting, auto-refactoring, tons of customizable keyboard shortcuts, etc.

Visual Studio Code (VSCode) is currently the most-popular code editor for reasons like being lightweight, cleaner, large marketplace of extensions, integrated Source Control features, debugger, remote explorer support, Regular Expression (regex) based find/replace, etc.

In fact, a workspace configuration file for vscode.vscode/settings.json has already been added. Recommended extensions for this project are Babel JavaScript, Dart, Docker, ESLint, Git Graph, GitLens, markdownlint, Prettier, SCSS IntelliSense, and SVG.

All that, however, shouldn't necessarily stop you from using Emacs, Nano, or Vim, if that's your poison :D. Happy coding!