wasm-micro-runtime/test-tools/wamr-ide
Wenyong Huang e2403c3ee9
Update documents (#984)
Fix wamr-ide link error, set wamr-ide to experimental and fix README issues
2022-01-25 20:24:33 +08:00
..
Media Implement WAMR-IDE with vscode extension (#943) 2022-01-25 10:10:12 +08:00
VSCode-Extension Implement WAMR-IDE with vscode extension (#943) 2022-01-25 10:10:12 +08:00
WASM-Source-Debug-Server/Docker Implement WAMR-IDE with vscode extension (#943) 2022-01-25 10:10:12 +08:00
WASM-Toolchain-Provider/Docker Implement WAMR-IDE with vscode extension (#943) 2022-01-25 10:10:12 +08:00
README.md Update documents (#984) 2022-01-25 20:24:33 +08:00

WAMR-IDE (Experimental)

Introduction

The WAMR-IDE is an Integrated Development Environment to develop WebAssembly application with coding, compiling and source debugging support. It contains 3 components: VSCode extension, WASM-toolchain-provider docker image and WASM source debug server docker image.

  • VSCode extension is an extension which can be installed in vscode, with which user can build and manage projects, develop wasm application, including building, running and debugging.

  • WASM-toolchain-provider is a docker image which provides building environment for wasm.

  • WASM source debug server is a docker image which provides running and source debugging environment for wasm application.


How to setup WAMR IDE

  1. Install VSCode on host.

    • make sure the version of vscode you installed is at least 1.59.0
  2. Install Docker on host.

    1. Windows: Docker Desktop
    2. Ubuntu: Docker Engine
      OS requirements:
      To install Docker Engine, you need the 64-bit version of one of these Ubuntu versions:
      - Ubuntu Impish 21.10
      - Ubuntu Hirsute 21.04
      - Ubuntu Focal 20.04(LTS)
      - Ubuntu Bionic 18.04(LTS)
      
  3. Build docker images

    We have 2 docker images which should be built or loaded on your host, wasm-toolchain-provider and wamr-debug-server. To build these 2 images, please enter the WASM_Source_Debug_Server/Docker & WASM_Toolchain/Docker, then execute the build_docker_image script respectively.

     ```shell
     $ cd WASM_Toolchain/Docker
     $ ./build_docker_image.bat # or ./build_docker_image.sh on linux
     $ cd WASM_Source_Debug_Server/Docker
     $ ./build_docker_image.bat # or ./build_docker_image.sh on linux
     ```
    
  4. Generate wamride extension package file

    wamride-0.0.1.vsix can be packaged by npm vsce.

    Note that patched lldb should be built and put into the VSCode_Extension/resource/debug folder before your package or extension debug process if you want to enable source debugging feature. Please follow this instruction to build lldb.

    You can also debug the extension directly follow this instruction without packing the extension.

  5. Install extension from vsix

    install_from_vsix

    and select wamride-0.0.1.vsix which you have saved on your host.


How to use wamr-ide

WAMR-IDE extension contains 2 components as following picture showing. Project management and Execution management

wamr_ide_main_menu

Project Management

  1. New project

    When you click New project button, extension will pop up a message box at the bottom right of the screen as picture showing.

    set_up_workspace_message

    You can click Set up now and select the target folder to create project workspace, click Maybe later to close the message box.

    Note that your selected workspace folder should be empty.

    After setting up workspace, extension will prompt successful message:

    workspace set up successfully!
    

    Then click New project button again, a new page will show as following.

    new_project_page

    Enter the project name and select the template, then click Create button. And a new project will be generated and opened in your current vscode window or in a new vscode window.

    Opening in current windows or a new one depends on whether your vscode's explorer is empty or not. If empty, open in current window, or open in the new vscode window.

    A new initialized project is as following picture shows.

    project_template

    .wamr is the project configuration folder which contains 3 files, CMakeLists.txt, project.cmake and compilation_config.json. CMakeLists.txt is used to build wasm target and the project.cmake is included in CMakeLists.txt. project.cmake includes the user's customized configuration like those folders which should be added include path.

  2. Open project

    Click Open project button, quick-pick-box will show as following. All projects under your current workspace will be shown and can be selected.

    configuration file

  3. Change workspace

    Click Change workspace button, a dialog will show as following. You can select 1 folder in file system as workspace, and the new workspace path will override previous workspace, and all new created projects will be generated in the new workspace.

    change workspace

  4. Configuration Click Configuration button, a new page will be shown as following. You can config building target with Include paths, Initial & Max linear memory, stack size, exported_symbols and include paths, exclude files.

    config building target

    Then click Modify button to confirm, if configurations are modified successfully and following message will pop. Click OK, the page will be auto closed.

    save configuration

    And all configuration will be saved in .wamr/compilation_config.json.

    configuration file

  5. Customize include paths and exclude source files

    Extension supports adding header file folder to include path and excluding source file from build.

  • Add to include path

    • Move the cursor to the folder and right click, then menus will be shown as following. Click Toggle state of path including.

    right click menus

  • Exclude source file from build

    • Move the cursor to the source file and right click, then menus will be shown as following. Click Toggle state of excluding.

    right click menus

    After setting up include path and exclude files, the corresponding folder and files will be decorated with color and icon as following picture shows.

    decoration for files

    At the same time, all added include path and exclude files will be saved in .wamr/compilation_config.json as json array.

    compilation config

Toggle state of path including just shows when selecting folder and hides with other resources.

Toggle state of excluding just shows when selecting [.c | .cpp | .cxx] source files and hides with other resources.

Execution Management

  1. Build

    When you have completed coding and ready to build target, click build button and the wasm-toolchain will auto start a container and execute the building process.

    build terminal output

    After successful building execution, build folder will be generated in explorer, in which ${output_file_name}.wasm is exist.

    build folder

    Note that to start docker service firstly.

  2. Run

    Click Run button and wasm-debug-server docker image will auto start a container and execute the running process.

    run

  3. Debug

    Click Debug button will trigger start ip wamr-debug-server docker image, and boot up lldb debug server inside of iwasm. Then start a debugging session with configuration to connect. Tap F11 or click step into to start debugging.

    debug

    Docker containers will be auto stopped and removed after the execution.