Skip to content

Latest commit

 

History

History
204 lines (147 loc) · 7.51 KB

CONTRIBUTING.adoc

File metadata and controls

204 lines (147 loc) · 7.51 KB

Contributing

Download early access previews

Install from EAP repository

  1. Open Settings (or Preferences) then Plugins | ⚙️

  2. Select Manage Plugin Repositories…​

  3. Enter https://plugins.jetbrains.com/plugins/eap/list?pluginId=17096

Download the EAP from the plugin release page.

  1. Open Settings (or Preferences) then Plugins | ⚙️

  2. Select Install Plugin from Disk…​

Navigating the code base

This plugin has been bootstrapped from the IntelliJ Platform Plugin Template. It might be worth tracking upstream changes if they can be applied there too.

The whole project build is driven by Gradle as it is required to build the JetBrains plugin. Currently, the Gradle JVM needs to be JDK 17+; this can also be configured in IntelliJ via Settings | Build, Execution, Deployment | Build Tools | Gradle.

.
├── .github
│   └── workflows (6)
├── .run (7)
├── CHANGELOG.md (1)
├── excalidraw-assets (2)
├── plugin (3)
├── project-fixture (4)
└── settings.gradle.kts (5)

  1. The changelog to manually edit

  2. This is the Excalidraw React web-app, the Node/Yarn build is controlled by Gradle project

  3. This is the actual IntelliJ plugin code base, it’s a Gradle project

  4. Simple project to open in the sand-boxed IDE.

  5. Usual declaration of the gradle subprojects (excalidraw-assets and plugin)

  6. GitHub Action workflows

  7. IntelliJ IDEA’s run configurations (Run Plugin, etc.)

They are two main projects the excalidraw web-app and the IntelliJ plugin.

Excalidraw React web-app assets

excalidraw-assets
├── build.gradle.kts (1)
├── config-overrides.js (2)
├── node_modules (8)
├── package.json (3)
├── public (4)
│   └── index.html
├── src (5)
│   ├── App.tsx
│   ├── index.tsx
│   ├── react-app-env.d.ts
│   └── styles.css
├── tsconfig.json (6)
└── yarn.lock (7)

  1. The Gradle build configuration, configure node and yarn tasks, also defines input/output for better cache-ability.

  2. This is a webpack override configuration, used by react-app-rewired, in particular it allows to inline source maps to allow debugging in a JCEF devtools.

  3. Usual package.json that declares dependencies, with unbounded ranges.

  4. The location of the index.html

  5. The location of the React app sources in typescript.

  6. Configuration file necessary for typescript.

  7. A Yarn lock file represents the exact dependencies, it allows reproducible builds.

  8. The node_modules folder is where the dependencies are downloaded. Its location is hardcoded in node or npm.

A note about the Excalidraw React Web App

JS and React are stranger things to me, their official documentation can be overwhelming at first; I found the following blog post useful to introduce me to basic concepts.

On the same topic, here’s a blog post with the typescript angle.

Plugin code base

The plugin is a usual Gradle project, most of the sources are written in Kotlin.

TODO : describe plugin.xml, and package structure.

Running the plugin in the sand-boxed environment

Use the predefined task Run Plugin, whose configuration is saved in the .run folder.

You can also use the Gradle command

Running the sandboxed IDE with the Excalidraw plugin
./gradlew :plugin:runIde
Tip

When running the sand-boxed IDE, the web-app path is overridden via these two system properties

  • excalidraw.internal.webappPath, this is the path to the index.html file and the web-app support files (js, css, etc.)

  • excalidraw.internal.webappExcalidrawAssetsPath, this is the path to the excalidraw-assets folder (containing excalidraw app itself and fonts).

Currently, these folders are configured in excalidraw-assets/build.gradle.kts to subfolders in the build directory

excalidraw-assets
├── build
│   ├── assets (1)
│   ├── react-build (2)
│   └── ...
└── ...

  1. Path passed to excalidraw.internal.webappExcalidrawAssetsPath

  2. Path passed to excalidraw.internal.webappPath

This allows modifying the web-app without having to rebuild the plugin. However, at this time building the web-app still requires building / assembling the web-app.

In short modify the web-app, then run:

./gradlew :excalidraw-assets:assembleFrontend

Plugin DEBUG logs

This plugin is using the diagnostic logger at DEBUG level, that means the log events will be appended in the usual idea.log.

However, the log category has to be configured at DEBUG level, in order to do so

  1. Run the plugin configuration

  2. Once the sand-boxed IDE is ready, open Help | Diagnostic Tools | Debug Log Settings…​

  3. Enter #com.github.bric3.excalidraw

The sand-boxed IDE’s log file is located here : plugin/build/idea-sandbox/system/log/idea.log.

Once the sandbox has been run once, this configuration will appear in the following file under the following element:

plugin/build/idea-sandbox/config/options/other.xml
/application/component[@name='PropertiesComponent']/property[@name='log.debug.categories']

Inspect UI

The sand-boxed IDE should be launched with internal mode enabled.

Enable UI Inspector : Tools > Internal Actions > UI > UI Inspector

Dependencies source code

Unfortunately, some dependencies sources are not available, in particular rd. This project was bumped to 2022.2 and gradle-intellij-plugin is now able to pull the sources, which now embed the ones of JCef are embedded.

If this is ever interesting to you, it’s possible to clone sources of [JetBrains/jcef](https://github.com/JetBrains/jcef). Whe running the app one can use the JCEF type org.cef.CefApp, and get the version something along CefApp.getInstance().getVersion() then checkout the matching branch e.g. git checkout cef-81.2.24.

JetBrains/rd

Part of this code is generated from C/C#, however types that are interacted with are available in this rd project. Since updating to 2022.2 the jar don’t have the version in its name, so unsure about what’s following but the releases seems somewhat aligned to IntelliJ releases so 2022.5 then navigate the repo to the associated tag.

Official documentation