Skip to content

Latest commit

 

History

History
465 lines (313 loc) · 22.3 KB

Moddable SDK - Getting Started.md

File metadata and controls

465 lines (313 loc) · 22.3 KB
Raw

Moddable SDK – Getting Started

A guide to installing the Moddable SDK and building its tools

Copyright 2016-2023 Moddable Tech, Inc.
Revised: October 12, 2023

This document provides instructions to install the Moddable SDK and build its tools on the computer you use for development.

Table of Contents

Overview

To get started with the Moddable SDK, take the following steps:

Step 1: Build the Moddable SDK tools

Follow the Installing instructions in the section below for your computer's OS. These instructions will have you verify your setup by running the helloworld example on a desktop simulator using mcconfig, a command line tool that builds and runs Moddable applications.

For more information about the desktop simulator, see the Simulator section of the tools documentation.

You will also learn how to open xsbug, the JavaScript source level debugger that is built as part of the Moddable SDK tools. xsbug is a full featured debugger that supports debugging modules and applications for XS platforms.

Similar to other debuggers, xsbug supports setting breakpoints, browsing source code, the call stack and variables. The xsbug debugger additionally provides real-time instrumentation to track memory usage and profile application and resource consumption.

For more information abut xsbug, see the xsbug documentation.

Step 2: Install tools for your target platform(s)

To run applications on a device, you have to install the required SDKs, drivers and development tools for your target platform. The devices folder contains instructions for all MCUs supported by the Moddable SDK. See the What's Next: Building and Running Apps on Development Boards and MCUs section of this document for more details and links to instructions for your target platform.

Step 3: Try out some examples

This repository includes over 150 example apps that demonstrate how to use many features of the Moddable SDK. Many are less than one page of source code to focus on demonstrating how to use a specific capability.

Step 4: Build your own apps

When you are ready to customize the example apps or build your own from scratch, documentation and source code for all of the JavaScript APIs is available. All documentation is provided in markdown format. Software modules that make up the runtime of the Moddable SDK are in the modules directory.

The documentation, examples, and modules directories share a common structure to make it straightforward to locate information.

  • base: Fundamental runtime capabilities including time, timer, debug, instrumentation, and UUID
  • commodetto: Bitmap graphics library
  • crypt: Cryptographic primitives and TLS
  • data: Base64 and hex encoding
  • drivers: Device drivers for displays, touch inputs, sensors, and expanders
  • files: Storage capabilities including files, flash, preferences, resources, and zip
  • network: Network socket and protocols built on socket including HTTP, WebSockets, DNS, SNTP, telnet, and TLS; also, Wi-Fi and BLE APIs.
  • pins: Hardware protocols including digital (GPIO), analog, PWM, and I2C
  • piu: User interface framework

macOS

System Requirements

The Moddable SDK requires macOS Sierra (Version 10.12) or newer and a full installation of Xcode version 9 or newer.

Installing

  1. Download and install Xcode. Launch Xcode to install additional command line components when prompted.

  2. Create a Projects directory in your home directory at ~/Projects for the Moddable SDK repository.

    Note: The Moddable SDK repository can be downloaded to any directory. These instructions assume the Moddable SDK is downloaded to the ~/Projects directory.

  3. Download the Moddable repository, or use the git command line tool as follows:

    cd ~/Projects
git clone https://github.com/Moddable-OpenSource/moddable

  4. Open your shell startup/initialization file.

    For macOS Mojave and earlier, the default shell is bash, so you should open ~/.profile.

    open ~/.profile

    Starting with macOS Catalina, the default shell is zsh, so you should open ~/.zshrc.

    open ~/.zshrc

    Note: If executing the above command gives you an error saying that your shell startup/initialization file does not exist, you can create the appropriate file using the touch command. For example, touch ~/.zshrc.

  5. Add the following lines to the file you just opened and save. This sets up the MODDABLE environment variable to point at your local Moddable SDK repository directory and edits the PATH environment variable to include the Moddable built tools directory.

    export MODDABLE="/Users/<user>/Projects/moddable"
export PATH="${MODDABLE}/build/bin/mac/release:$PATH"

  6. Adding the export statements to your ~/.profile or ~/.zshrc does not update the environment variables in active shell instances, so open a new shell instance (by opening a new tab/window) or manually run the export statements in your shell before proceeding.

  7. Build the Moddable command line tools, simulator, and debugger from the command line:

    cd ${MODDABLE}/build/makefiles/mac
make

  8. Launch the xsbug debugger from the command line:

    open ${MODDABLE}/build/bin/mac/release/xsbug.app

  9. Verify the host environment setup by building the starter helloworld application for the desktop simulator target:

    cd ${MODDABLE}/examples/helloworld
mcconfig -d -m -p mac

  10. IMPORTANT: You can now build and run applications for the desktop simulator. To build and run applications on a development board or MCU, you need to install additional SDKs, drivers, and development tools for your target platform. See the What's Next (Building and Running Apps on Development Boards and MCUs) section of this document for more details and links to instructions.

Troubleshooting

  • If the Moddable SDK build fails with an error like "xcode-select: error: tool 'ibtool' requires Xcode, but active developer directory '/Library/Developer/CommandLineTools' is a command line tools instance." there are three potential issues and fixes:
    1. You may have a command line tools-only Xcode installation. The Moddable SDK build requires a full installation of Xcode.
    2. You may need to launch the Xcode application to accept Xcode's license agreement and install the command line components.
    3. If you have a full Xcode installation but your build fails with this error, you need to use the xcode-select utility to select your full Xcode installation. This can be done with this command, with the path adjusted as necessary for your environment: sudo xcode-select -s /Applications/Xcode.app/Contents/Developer

Updating

The Moddable SDK tools are frequently updated with improvements and added functionality. You should occasionally update your host environment by following these steps:

  1. Update your local clone of the Moddable repository:

    cd $MODDABLE
git pull

    Note that if you have any local changes to Moddable repository files, you may need to stash your changes and then reapply them after pulling:

    cd $MODDABLE
git stash push
git pull
git stash pop

  2. Delete any existing Moddable SDK build outputs:

    cd $MODDABLE
rm -rf build/bin
rm -rf build/tmp

  3. Build the Moddable command line tools, simulator, and debugger:

    cd ${MODDABLE}/build/makefiles/mac
make

  4. Verify the host environment setup by building the starter helloworld application for the desktop simulator target:

    cd ${MODDABLE}/examples/helloworld
mcconfig -d -m -p mac

Windows

System Requirements

The Moddable SDK requires Windows 8.1 or newer and Microsoft Visual Studio Community 2017 or newer. We recommend Windows 10 or Windows 11 and Microsoft Visual Studio Community 2022.

Installing

  1. Download the Microsoft Visual Studio 2022 Community installer.

  2. Launch the installer. On the "Workloads" tab, select the "Desktop development for C++" option. On the "Individual Components" tab, select "Windows 10 SDK (10.0.19041.0)" (this should be preselected on Windows 10 systems but must be manually included on Windows 11 systems). Proceed with the installation as configured.

  3. Create a Projects directory in your %USERPROFILE% directory, e.g. C:\Users\<your-user-name> for the Moddable SDK repository.

    Note: The Moddable SDK repository can be downloaded to any directory. These instructions assume the Moddable SDK is downloaded to the %USERPROFILE% directory.

  4. Download the Moddable repository, or use the git command line tool as follows:

    cd %USERPROFILE%\Projects
git clone https://github.com/Moddable-OpenSource/moddable

  5. Open the "Environment Variables" dialog of the Control Panel app by following these instructions. From that dialog:

  • Create a User Variable called MODDABLE and set it to point at your local Moddable SDK repository directory. Update the path as necessary for you system by navigating to the Moddable SDK folder using the "Browse Directory..." button.

    • Variable Name: MODDABLE
    • Variable Value: %USERPROFILE%\Projects\moddable

  • Edit the User Variable Path to include the Moddable SDK tools directory. Update the path as necessary for your system by navigating to the correct folder using the "Browse..." button.

    • Variable Name: Path
    • Variable Value (add to the existing list): %USERPROFILE%\Projects\moddable\build\bin\win\release

    Note: The %USERPROFILE%\Projects\moddable\build\bin\win\release directory will be created in the next step. It is safe to set the environment variable now or to come back after Step 6 to add it to the Path.

    Note: Make sure you open a new Command Prompt after setting the environment variables. The new environment settings will not take effect in existing Command Prompt instances.

  1. Launch the "x86 Native Tools Command Prompt for VS 2022" command line console. Build the Moddable command line tools, simulator, and debugger from the command line:

    cd %MODDABLE%\build\makefiles\win
build

    Note: There is an alternative build batch file called parallel_build.bat that can be used on multi-core systems to significantly speed up the Moddable SDK build. It is, however, more difficult to see diagnostic error messages when using this batch file. If build.bat works correctly on your system, consider using parallel_build.bat for future Moddable SDK builds.

  2. Launch the xsbug debugger from the command line:

    xsbug

  3. Verify the host environment setup by building the starter helloworld application for the desktop simulator target:

    cd %MODDABLE%\examples\helloworld
mcconfig -d -m -p win

  4. IMPORTANT: You can now build and run applications for the desktop simulator. To build and run applications on a development board or MCU, you need to install additional SDKs, drivers, and development tools for your target platform. See the What's Next (Building and Running Apps on Development Boards and MCUs) section of this document for more details and links to instructions.

Troubleshooting

  • If the Moddable SDK build fails with an error like "LINK : fatal error LNK1104: cannot open file '<Moddable path>\build\bin\win\release\<tool name>.exe'", it most likely indicates a conflict with antivirus software as described in this document from Microsoft. Please try excluding the %MODDABLE% directory from your antivirus software's live scanning capability during the build process.

  • If the Moddable SDK build fails with the error "'nmake' is not recognized as an internal or external command, operable program or batch file." there are three potential issues and fixes:

    1. You may not have Visual Studio installed. We recommend using the Microsoft Visual Studio 2022 Community Edition installer.
    2. When you installed Visual Studio, you may not have chosen the "Desktop development for C++" workload option. Re-run the installer and choose that workload for installation.
    3. You may have inadvertently attempted the build in the default Command Prompt rather than the "x86 Native Tools Command Prompt for VS 2022." This Command Prompt sets important environment variables for the build and can be found by searching for "x86 Native Tools" in the Start Menu.

  • If the Moddable SDK build fails with an error like "fatal error LNK1112: module machine type 'x64' conflicts with target machine type 'x86'", you have most likely attempted the build in the "x64 Native Tools Command Prompt for VS 2022" rather than the correct "x86 Native Tools Command Prompt for VS 2022." This Command Prompt sets important environment variables for the build and can be found by searching for "x86 Native Tools" in the Start Menu.

Updating

The Moddable SDK tools are frequently updated with improvements and added functionality. You should occasionally update your host environment by following these steps.

> Note: The following commands should all be run in the "x86 Native Tools Command Prompt for VS 2022" command line console.

  1. Update your local clone of the Moddable repository:

    cd %MODDABLE%
git pull

    Note that if you have any local changes to Moddable repository files, you may need to stash your changes and then reapply them after pulling:

    cd %MODDABLE%
git stash push
git pull
git stash pop

  2. Delete any existing Moddable SDK build outputs:

    cd %MODDABLE%\build\makefiles\win
build clean

  3. Build the Moddable command line tools, simulator, and debugger:

    cd %MODDABLE%\build\makefiles\win
build

    Note: There is an alternative build batch file called parallel_build.bat that can be used on multi-core systems to significantly speed up the Moddable SDK build. It is, however, more difficult to see diagnostic error messages when using this batch file. If build.bat works correctly on your system, consider using parallel_build.bat for future Moddable SDK builds.

  4. Verify the host environment setup by building the starter helloworld application for the desktop simulator target:

    cd %MODDABLE%\examples\helloworld
mcconfig -d -m -p win

Linux

System Requirements

The Moddable SDK has been tested on the Ubuntu 16.04-22.04 LTS (64-bit) and Raspberry Pi Desktop (32-bit) operating systems. These instructions assume that a GCC toolchain has already been installed.

Installing

  1. Install or update the packages required to compile:

    sudo apt-get install gcc git wget make libncurses-dev flex bison gperf

  2. Install the development version of the GTK+ 3 library:

    sudo apt-get install libgtk-3-dev

    Note: If you are installing for WSL2 on Windows, install the following icon pack:

    sudo apt-get install adwaita-icon-theme-full

  3. Create a Projects directory in your home directory at ~/Projects for the Moddable SDK repository.

    Note: The Moddable SDK repository can be downloaded to any directory. These instructions assume the Moddable SDK is downloaded to the ~/Projects directory.

  4. Download the Moddable repository, or use the git command line tool as follows:

    cd ~/Projects
git clone https://github.com/Moddable-OpenSource/moddable

  5. Setup the MODDABLE environment variable in your ~/.bashrc file to point at your local Moddable SDK repository directory. Add the Moddable built tools directory to your PATH:

    export MODDABLE=~/Projects/moddable
export PATH=$PATH:$MODDABLE/build/bin/lin/release

    Note: You must open a new shell instance or manually run the export statements in your shell before proceeding. Adding the export statements to your ~/.profile does not update the environment variables in active shell instances.

  6. Build the Moddable command line tools, simulator, and debugger from the command line:

    cd $MODDABLE/build/makefiles/lin
make

  7. Install the desktop simulator and xsbug debugger applications:

    cd $MODDABLE/build/makefiles/lin
make install

    When prompted, enter your sudo password to copy the application's desktop, executable and icon files into the standard /usr/share/applications, /usr/bin, and /usr/share/icon/hicolor directories.

  8. Launch the xsbug debugger from the command line:

    xsbug

  9. Verify the host environment setup by building the starter helloworld application for the desktop simulator target:

    cd $MODDABLE/examples/helloworld
mcconfig -d -m -p lin

    See this discussion for a description of what you should expect to see.

  10. IMPORTANT: You can now build and run applications for the desktop simulator. To build and run applications on a development board or MCU, you need to install additional SDKs, drivers, and development tools for your target platform. See the What's Next (Building and Running Apps on Development Boards and MCUs) section of this document for more details and links to instructions.

Updating

The Moddable SDK tools are frequently updated with improvements and added functionality. You should occasionally update your host environment by following these steps:

  1. Ensure that the development version of the GTK+ 3 library is installed and up to date:

    sudo apt-get update
sudo apt-get install libgtk-3-dev
sudo apt-get upgrade libgtk-3-dev

  2. Update your local clone of the Moddable repository:

    cd $MODDABLE
git pull

    Note that if you have any local changes to Moddable repository files, you may need to stash your changes and then reapply them after pulling:

    cd $MODDABLE
git stash push
git pull
git stash pop

  3. Delete any existing Moddable SDK build outputs:

    cd $MODDABLE
rm -rf build/tmp
rm -rf build/bin

  4. Build the Moddable command line tools, simulator, and debugger:

    cd $MODDABLE/build/makefiles/lin
make

  5. Install the desktop simulator and xsbug debugger applications:

    cd $MODDABLE/build/makefiles/lin
make install

    When prompted, enter your sudo password to copy the application's desktop, executable and icon files into the standard /usr/share/applications, /usr/bin, and /usr/share/icon/hicolor directories.

  6. Verify the host environment setup by building the starter helloworld application for the desktop simulator target:

    cd $MODDABLE/examples/helloworld
mcconfig -d -m -p lin

What's Next: Building and Running Apps on Development Boards and MCUs

To build and run applications on a development board or MCU, you will need to install additional SDKs, drivers, and development tools for your target platform. These tools are provided by the manufacturer of the MCU and are not part of the Moddable SDK, but the devices folder contains instructions we wrote to guide you through the installation process.

The table below links to some of the documents in the devices folder to help you quickly find instructions for your target platform:

Device Documents
ESP32 or ESP32-based products
including Moddable Two, NodeMCU ESP32,
and M5Stack development boards		 Using the Moddable SDK with ESP32
ESP8266 or ESP8266-based products
including Moddable One, Moddable Three,
and NodeMCU ESP8266		 Using the Moddable SDK with ESP8266
Giant Gecko, Mighty Gecko,
Thunderboard Sense 2, or Blue Gecko		 Using the Moddable SDK with Gecko
QCA4020 Using the Moddable SDK with QCA4020
Raspberry Pi Pico Using the Moddable SDK with Pico
Nordic nRF52 Using the Moddable SDK with nRF52