blog!
i'm a big fanrustand variousIntelligent Integrated Development EnvironmentSo naturally I'm an avid power userIntelliJ Rust plugin。
While using the plugin, I noticed some small bugs that bothered me and the lack of some useful features. I wondered if there was anything I could do to improve the situation, so I checked the plugin repository to see if there was anything I could help fix.
Turns out the answer is yes - I found the problem in the comments, sent myfirst pull requestApproved and connected(!) within 4 minutes. The kind responses I've received from the plugin maintainers have inspired me to keep improving the plugin, which I've found over time to be very enjoyable and useful - fromtoday, I opened more than100 PR eggsin the plugin repository
. Mainly thanks to the maintainer of the plugin@wending,@vlad20012,@mchernyavskyI@ortemfor tracking my pull requests :)
Since contributing to a non-trivial open source project can be intimidating at first, I decided to document some of my experiences in this blog series to inform those who also want to contribute to this plugin. I was inspired by a similar blog post describingContributions to the Rust profiler。
My goal is to provide a simple guide that can inspire more people to contribute to this wonderful plugin and describe the basic open source contribution workflow. I plan to write these posts as a retrospective description of how I approach my contributions, and to provide additional insights that should be helpful for your own contributions.
In this first blog post, I'll show you how to set up a basic environment for testing and modifying plugins, and I'll also describe its basic architecture. In the next post, I'll walk through my first contribution, from identifying the issue, to implementing the bug fix, to submitting a pull request. In later articles, I'd like to explain more complicated things like creating new intents, inspections or annotations, tweaking code shapers, or even designing entirely new refactoring operations.
- Next article:#1 Fixing a Simple Nest Mistake
give up: I'm not an expert on IntelliJ API/plugins or Rust. What I have written here may not be correct or complete. Please let me know if you find something similarReddit！
This series has some prerequisites that I can't describe in detail:
- KotlinThe plugin is written almost entirely in a programming languageKotlin, so you should be familiar with it to follow it. If you know Java, C#, or another high-level C-based language, it should look very familiar.
- rustThe plugin allows for Rust integration, so of course I'll be talking a lot about Rust. You don't need to be very familiar with it, but I assume you know the basics or at least are familiar with Rust's syntax rules.
- i get the ideaI will use IntelliJ IDEA to develop the plugin, since building and modifying the plugin can be done right away in this IDE. However, the plugin can be built, modified and tested using any other IDE or text editor. However, the plugin is specific to IntelliJ, so we'll discuss a lot of IntelliJ concepts.
- （git) Contributing to open source projects usually requires using some version control system, in this case git. I assume I know some basics of git, though I'll briefly describe how to contribute to other GitHub repositories.
- （Linux) I'll use some command line snippets that assume a Linux (or more specifically Ubuntu) environment. However, these commands should look very similar on other operating systems and are usually not needed if you use IDEA to work with add-ins.
With that out of the way, let's set up the plugin so we can build and test it!
If you want to use the plugin with IntelliJ IDEA, you can download the free community versionhereIf you want to use the plugin, I recommend this IDE.
thisContributed filesPlugins already do a good job of advising new contributors how to build and contribute plugins. I used it extensively when I first started contributing, and I encourage you to read it first. The rest of this blog post will be heavily inspired by this document.
Before we download the plugin, you need to make sure you have it installedgitme aloneJDK. I recommend installingJDK8, that isrespectedAccording to the IntelliJ documentation.
$Sudoapt-getInstallgit openjdk-8-jdkedit: fromrecently, the plugin has been moved toJDK11：
$Sudoapt-getInstallopenjdk-11-jdkwe hope,JDKgit should be the only dependency we need, the plugin build system will take care of the rest.
Now we can clone the plugin repository:
$git clone https://github.com/intellij-rust/intellij-rust$CDintellij-restThe plugin uses the Gradle build system, so building is as simple as callingwriteTasks in the plugin directory:
$./gradlew:compileThis command will download a lot of packages as well as two IDEs (CLion and IDEA) which will be used as sandbox environments to test plugins, so prepare at least a few GB of disk space for this. If you're running this on a HDD, you'll also need a cup of coffee.
You can also build the project in IDEA by opening the project directory and building/running the "Run CLion" or "Run IDEA" configuration.
There are also some other useful gradle tasks:
./gradlew :plugin:runIde -PbaseIDE=clion- Open CLion with current plugin version./gradlew : Plugin: runIde -PbaseIDE=ideja- Open IDEA with the current plugin version./gradlew:test- run all tests (takes a long time)./gradlew:test --test *MyFavoriteTest*- Execute specific tests./gradlew :plugin:buildPlugin- Publish the plugin so it can be installed from disk
You can also call all of these directly from IDEA using the Gradle window.
This plugin basically reimplements most of therustinterface, which makes some of its internals relatively complex - it has its own Rust lexer and parser that infers types, resolves names, resolves functions, and understands modules and crates. While this may seem daunting at first, when you want to modify a plugin, you usually don't need to delve into these subsystems, just use them as a black-box API. I'll comment on things like type inference or name resolution in a later blog post as we need them for various functions. If you want to learn more, the plugin's architecture is atPlugin Documentation。
However, what we need to know right away is the plugin directory hierarchy, so we know where to look if we want to modify some code. There are several modules in the root directory of the plugin, the most important of which are:
: source code- in the Rust plugin:intellij-toml- in the TOML plugin: Tomr- TOML + Rust integration specific code (I meancharges.toml）:usually- Common code shared by Rust and TOML plugins:idea- IDEA integrates specific code: Clion- CLion integration specific code:Debugger- Rust debugger specific code
As you can see, there are actually two plugins in the repository - TOML and Rust. Most of my contributions are to Rust plugins, so that's what we'll coversource codeTable of contents.
That's pretty much all we need to know for now, and we'll explore the various parts of the plugin as we need them for specific functionality.
You should now have a working development environment set up so that you can modify plugins, build and test plugins. existnext post, we'll actually implement something and fix a simple
。
You can comment on this post atReddit。