docs: add instructions about Rust setup and version requirements

itsaky · itsaky · commit 75a8a060116f · 2024-02-18T21:35:04.000+05:30
diff --git a/README.md b/README.md
@@ -1,6 +1,8 @@
 # android-tree-sitter
-<a href="https://github.com/itsaky/AndroidIDE"><img src="https://androidide.com/github/img/androidide.php?part&for-the-badge"/></a><br><br> 
-Android Java bindings for [tree-sitter](https://tree-sitter.github.io/tree-sitter/). Currently used in [AndroidIDE](https://github.com/AndroidIDEOfficial/AndroidIDE)
+
+<a href="https://github.com/itsaky/AndroidIDE"><img src="https://androidide.com/github/img/androidide.php?part&for-the-badge"/></a><br><br>
+Android Java bindings for [tree-sitter](https://tree-sitter.github.io/tree-sitter/). Currently used
+in [AndroidIDE](https://github.com/AndroidIDEOfficial/AndroidIDE)
 and [sora-editor](https://github.com/Rosemoe/sora-editor).
 
 ## Add to your project
@@ -17,6 +19,7 @@ implementation 'com.itsaky.androidide.treesitter:tree-sitter-<language>:<version
 ```
 
 The following grammars have been published to Maven central :
+
 - Java
 - JSON
 - Kotlin
@@ -30,18 +33,31 @@ The following grammars have been published to Maven central :
 
 - Android NDK
 - `JDK 11` or newer.
-  - `JAVA_HOME` must be set to a JDK installation containing header files in the `JAVA_HOME/include` directory. The JDK bundled with Android Studio does not contain these headers.
-- `build-essential`, `cargo`, `nodejs`, `cmake` and `ninja-build` packages are required for builds. Install them with :
+    - `JAVA_HOME` must be set to a JDK installation containing header files in
+      the `JAVA_HOME/include` directory. The JDK bundled with Android Studio does not contain these
+      headers.
+- `build-essential`, `nodejs`, `cmake` and `ninja-build` packages are required for builds.
+  Install them with :
   ```
-  sudo apt install build-essential cargo nodejs cmake ninja-build
+  sudo apt install build-essential nodejs cmake ninja-build
   ```
-- [`tree-sitter-cli`](https://github.com/tree-sitter/tree-sitter/tree/master/cli) - To build grammars.
 
-As tree-sitter is already included in the source (as a submodule), the `tree-sitter-cli` is built from source and then used to build the grammars.
+- You'll also need to install `rust` and `cargo` (>= v1.74.0). Follow the
+  instructions [here](https://www.rust-lang.org/learn/get-started) to get started with the
+  installation.
+
+- [`tree-sitter-cli`](https://github.com/tree-sitter/tree-sitter/tree/master/cli) - To build
+  grammars.
 
-Read [the documentation](https://github.com/tree-sitter/tree-sitter/tree/master/cli) on how to install pre-built versions of `tree-sitter`.
+As tree-sitter is already included in the source (as a submodule), the `tree-sitter-cli` is built
+from source and then used to build the grammars.
 
-If you want to use a prebuilt `tree-sitter` binary (either manually installed or installed with `npm` or `cargo`), make sure it is accessible in the `PATH`, then set the `TS_CLI_BUILD_FROM_SOURCE` environment variable :
+Read [the documentation](https://github.com/tree-sitter/tree-sitter/tree/master/cli) on how to
+install pre-built versions of `tree-sitter`.
+
+If you want to use a prebuilt `tree-sitter` binary (either manually installed or installed
+with `npm` or `cargo`), make sure it is accessible in the `PATH`, then set
+the `TS_CLI_BUILD_FROM_SOURCE` environment variable :
 
 ```bash
 export TS_CLI_BUILD_FROM_SOURCE=false
@@ -59,30 +75,51 @@ git clone --recurse-submodules https://github.com/AndroidIDEOfficial/android-tre
 
 ### Build
 
-A normal Gradle build (`./gradlew build`) can be executed in order to build everything for Android _and_ the host OS. To build `android-tree-sitter` and the grammars _only_ for the host OS, you can execute `buildForHost` task on appropriate subprojects.
+A normal Gradle build (`./gradlew build`) can be executed in order to build everything for Android
+_and_ the host OS. To build `android-tree-sitter` and the grammars _only_ for the host OS, you can
+execute `buildForHost` task on appropriate subprojects.
 
 ## Adding grammars
 
-The Gradle modules for the grammars are almost identical, with only minor differences in the CMakeLists file and the Java binding class.
+The Gradle modules for the grammars are almost identical, with only minor differences in the
+CMakeLists file and the Java binding class.
 
-These Gradle modules are automatically generated by the [`DynamicModulePlugin`](https://github.com/AndroidIDEOfficial/android-tree-sitter/tree/dev/build-logic/ats/src/main/java/com/itsaky/androidide/treesitter/DynamicModulePlugin.kt). The generation process relies on the [`grammars.json`](https://github.com/AndroidIDEOfficial/android-tree-sitter/tree/dev/grammars/grammars.json) file. More information about the structure of this JSON file can be found in the [README](https://github.com/AndroidIDEOfficial/android-tree-sitter/blob/dev/grammars/README.md) under the `grammars` directory.
+These Gradle modules are automatically generated by
+the [`DynamicModulePlugin`](https://github.com/AndroidIDEOfficial/android-tree-sitter/tree/dev/build-logic/ats/src/main/java/com/itsaky/androidide/treesitter/DynamicModulePlugin.kt).
+The generation process relies on
+the [`grammars.json`](https://github.com/AndroidIDEOfficial/android-tree-sitter/tree/dev/grammars/grammars.json)
+file. More information about the structure of this JSON file can be found in
+the [README](https://github.com/AndroidIDEOfficial/android-tree-sitter/blob/dev/grammars/README.md)
+under the `grammars` directory.
 
-Apart from the `DynamicModulePlugin`, there are [other Gradle plugins](https://github.com/AndroidIDEOfficial/android-tree-sitter/tree/dev/build-logic/ats/src/main/java/com/itsaky/androidide/treesitter) which are used to configure and build the grammars effectively.
+Apart from the `DynamicModulePlugin`, there
+are [other Gradle plugins](https://github.com/AndroidIDEOfficial/android-tree-sitter/tree/dev/build-logic/ats/src/main/java/com/itsaky/androidide/treesitter)
+which are used to configure and build the grammars effectively.
 
-The common configuration for the grammars can be found in the [`build.gradle.kts`](https://github.com/AndroidIDEOfficial/android-tree-sitter/blob/52cc0400feee5079cac25b27d1e7b673ee53f436/build.gradle.kts#L136) file. This is where you can make changes or adjustments to the module configuration that applies to all grammars.
+The common configuration for the grammars can be found in
+the [`build.gradle.kts`](https://github.com/AndroidIDEOfficial/android-tree-sitter/blob/52cc0400feee5079cac25b27d1e7b673ee53f436/build.gradle.kts#L136)
+file. This is where you can make changes or adjustments to the module configuration that applies to
+all grammars.
 
-The generated modules are located in the `rootDir/grammar-modules` directory. This is where you can find the output of the module generation process.
+The generated modules are located in the `rootDir/grammar-modules` directory. This is where you can
+find the output of the module generation process.
 
 To add a new grammar to the project, follow these steps:
 
-1. Begin by adding the grammar source code to the `grammars` directory. To accomplish this, you can add a submodule using the following command:
-```bash
-git submodule add <remote_url> grammars/<language_name>
-```
-2. The `language_name` should be the simple name of the language, without the `tree-sitter-` prefix. This name is used to generate both the shared library and the Gradle module. For example, if the `language_name` is `abc`:
+1. Begin by adding the grammar source code to the `grammars` directory. To accomplish this, you can
+   add a submodule using the following command:
+
+    ```bash
+    git submodule add <remote_url> grammars/<language_name>
+    ```
+
+2. The `language_name` should be the simple name of the language, without the `tree-sitter-` prefix.
+   This name is used to generate both the shared library and the Gradle module. For example, if
+   the `language_name` is `abc`:
     - The module `tree-sitter-abc` will be automatically generated.
     - The name of the resulting shared library will be `libtree-sitter-abc.so`.
-3. After adding the grammar source, update the `grammars.json` file to include the newly added grammar in the project.
+3. After adding the grammar source, update the `grammars.json` file to include the newly added
+   grammar in the project.
 4. Finally, sync the project to trigger the generation of the module for the newly added grammar.
 
 ## Loading external grammars
@@ -92,16 +129,19 @@ You have two ways to load grammars that are not published along with this projec
 - Package the grammar with your application.
 - Load the grammar at runtime using `TSLanguage.loadLanguage`.
 
-`TSLanguage.loadLanguage` uses `dlopen` to load the library and must be CAREFULLY used. Also, grammars that are loaded using this method must be closed when they are not used.
+`TSLanguage.loadLanguage` uses `dlopen` to load the library and must be CAREFULLY used. Also,
+grammars that are loaded using this method must be closed when they are not used.
 
 > **_Prefer using the first method whenever possible._**
 
 ### Package the grammar with your application
 
-You can package the grammar in your Android application as you would package any other shared library :
+You can package the grammar in your Android application as you would package any other shared
+library :
 
 - Include the `libtree-sitter-myLang.so` file in the `jniLibs` directory of your project.
 - Create a native method in a Java class which will return the pointer to the language :
+
 ```java
 package com.my.app;
 
@@ -116,6 +156,7 @@ public class MyClass {
 ```
 
 - Write the C/C++ implementation for the method :
+
 ```c++
 extern "C" TSLanguage *tree_sitter_myLang();
 
@@ -130,62 +171,72 @@ Java_com_my_app_MyClass_myLang(JNIEnv *env, jclass clazz) {
 - Create and use the `TSLanguage` instance :
 
 ```java
-final TSLanguage myLang = TSLanguage.create("myLang", MyClass.myLang());
+final TSLanguage myLang=TSLanguage.create("myLang",MyClass.myLang());
 
 // use it with TSParser
-try (final var parser = TSParser.create()) {
+  try(final var parser=TSParser.create()){
   parser.setLanguage(myLang);
   ...
-}
+  }
 ```
 
 ### Load grammars at runtime
 
 > android-tree-sitter `v3.1.0` or newer is required for this method.
 
-`TSLanguage` provides `loadLanguage(String, String)` method which can be used to load the grammars at runtime. This method uses `dlopen` to load the shared library, get the language instance and return its pointer. Use this method CAREFULLY.
+`TSLanguage` provides `loadLanguage(String, String)` method which can be used to load the grammars
+at runtime. This method uses `dlopen` to load the shared library, get the language instance and
+return its pointer. Use this method CAREFULLY.
 
-The language instances created using this method **MUST** be closed using `TSLanguage.close()`. Calling the `close` method ensures that the underlying `dlopen`'ed library handle is closed using `dlclose`.
+The language instances created using this method **MUST** be closed using `TSLanguage.close()`.
+Calling the `close` method ensures that the underlying `dlopen`'ed library handle is closed
+using `dlclose`.
 
 Usage :
+
 ```java
 // provide the path to the shared library and the name of the language
 // the name is used to cache the language instance
 // further invocations of this method with the same lang name returns the
 // cached language instance
-final TSLanguage myLang = TSLanguage.loadLanguage("/path/to/libtree-sitter-myLang.so", "myLang");
+final TSLanguage myLang=TSLanguage.loadLanguage("/path/to/libtree-sitter-myLang.so","myLang");
 
-if (myLang != null) {
+  if(myLang!=null){
   // loaded successfully
-} else {
+  }else{
   // failed to load the language
   // see logcat for details
-}
+  }
 ```
 
 Use this language :
+
 ```java
-try (final var parser = TSParser.create()) {
+try(final var parser=TSParser.create()){
   parser.setLanguage(myLang);
   ...
-}
+  }
 ```
 
-You don't have to keep a reference to `myLang`. Once loaded, the language can be accessed using `TSLanguageCache` :
+You don't have to keep a reference to `myLang`. Once loaded, the language can be accessed
+using `TSLanguageCache` :
+
 ```java
 // returns the 'myLang' instance i.e. both are same
-final TSLanguage cachedMyLang = TSLanguageCache.get("myLang");
+final TSLanguage cachedMyLang=TSLanguageCache.get("myLang");
 ```
 
 **DO NOT FORGET** to close the language :
+
 ```java
 // this closes the underlying library handle
 myLang.close();
 ```
 
 ## Examples
 
-For examples, see the [tests](https://github.com/AndroidIDEOfficial/android-tree-sitter/tree/dev/android-tree-sitter/src/test/java/com/itsaky/androidide/treesitter).
+For examples, see
+the [tests](https://github.com/AndroidIDEOfficial/android-tree-sitter/tree/dev/android-tree-sitter/src/test/java/com/itsaky/androidide/treesitter).
 
 ## License
 
