wasm-micro-runtime/test-tools/wamr-ide/README.md

# 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](https://code.visualstudio.com/Download) you installed is at least _1.59.0_

2.  Install `Docker` on host.

    1. [Windows: Docker Desktop](https://docs.docker.com/desktop/windows/install/)
    2. [Ubuntu: Docker Engine](https://docs.docker.com/engine/install/ubuntu)
        ```xml
        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`](https://code.visualstudio.com/api/working-with-extensions/publishing-extension).

    > 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](../../doc/source_debugging.md#debugging-with-interpreter) to build `lldb`.
    >
    > **You can also debug the extension directly follow this [instruction](./VSCode_Extension/README.md) without packing the extension.**

5.  Install extension from vsix

    ![install_from_vsix](./Media/install_from_vsix.png "install wamr-ide 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](./Media/wamr_ide_main_menu.png "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](./Media/set_up_workspace_message.png "set up workspace message box")

    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:

    ```xml
    workspace set up successfully!
    ```

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

    ![new_project_page](./Media/new_project_page.png "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](./Media/project_template.png "default 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](./Media/open_project_page.png "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 ](./Media/change_workspace_dialog.png "change workspace dialog")

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](./Media/Config_building_target.png "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](./Media/save_configuration.png "save configuration")

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

    ![configuration file](./Media/compilation_config.png "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](./Media/right_click_menus_1.png "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](./Media/right_click_menus_2.png "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](./Media/decoration_for_files.png "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](./Media/compilation_config_2.png "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](./Media/build_terminal.png "build terminal output")

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

    ![build folder](./Media/build_folder.png "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](./Media/run.png "run wasm")

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](./Media/debug.png "source debugging")

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