From e570943ec50887c55f5b1aeee5d19ae4805e6c51 Mon Sep 17 00:00:00 2001 From: Erimel Date: Wed, 10 May 2023 13:57:23 -0400 Subject: [PATCH] Update contributing information (#673) Co-authored-by: Uriel Co-authored-by: Butterscotch! --- CONTRIBUTING.md | 110 +++++++++++++++++++++++++++++------------------- README.md | 18 ++++---- gui/LICENSE.md | 6 --- gui/README.md | 30 ------------- 4 files changed, 76 insertions(+), 88 deletions(-) delete mode 100644 gui/LICENSE.md delete mode 100644 gui/README.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4b4f5fde5..17987a258 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,50 +1,66 @@ # Contributing to SlimeVR -This document describes essential knowledge for contributors to SlimeVR. +This document describes essential knowledge required to contribute to the SlimeVR Server. -## How to get started +### Prerequisites -### Getting the code -First, clone the codebase using `git`. If you don't have `git` installed, go install it. +- [Git](https://git-scm.com/downloads) +- [Java v17+](https://adoptium.net/temurin/releases/) +- [Node.js v16+](https://nodejs.org) (We recommend the use of `nvm` instead of installing Node.js directly) +- [Microsoft Edge WebView2](https://developer.microsoft.com/en-us/microsoft-edge/webview2/#download-section) or `webkit2gtk` for Linux +- [Rust](https://rustup.rs) + +## Cloning the code +First, clone the codebase using git in a terminal in the folder you want. ```bash -# Clone repositories git clone --recursive https://github.com/SlimeVR/SlimeVR-Server.git - -# Enter the directory of the codebase -cd SlimeVR-Server ``` -Now you can open the codebase in your favorite IDE or text editor. - -### Installing Java -The codebase is required to build with Java version 17 or higher. - -```bash -# Check java version -java --version -``` +Now you can open the codebase in [IDEA](https://www.jetbrains.com/idea/download/) (Recommended; VSCode and Eclipse also work but have limited Kotlin support). -### Building the code -The code is built with `gradle`, a cli tool that manages java projects and their -dependencies. You can build the code with `./gradlew build` and run it with -`./gradlew run`. +## Building the code +### Java (server) -## Code Style -Code is autoformatted with [spotless](https://github.com/diffplug/spotless/tree/main/plugin-gradle). +The Java code is built with `gradle`, a CLI tool that manages java projects and their +dependencies. +- You can run the server by running `./gradlew run` in your IDE's terminal. +- To compile the code, run `./gradlew shadowJar`. The result will +be at `server/build/libs/slimevr.jar` (you can ignore `server.jar`). + +(Note: Your IDE may be able to do all of the above for you.) + +### Tauri (gui) + +- Run `npm install` in your IDE's terminal to download and install dependencies. +- To launch the GUI in dev mode, run `npm run gui`. +- Finally, to compile for production, run `npm run tauri build`. The result +will be at `target/release/slimevr.exe`. + +## Code style + +### Java (server) + +The Java code is auto-formatted with [spotless](https://github.com/diffplug/spotless/tree/main/plugin-gradle). Code is checked for autoformatting whenever you build, but you can also run `./gradlew spotlessCheck` if you prefer. -To autoformat your code from the command line, you can run `./gradlew spotlessApply`. -We recommend installing support for spotless in your IDE of choice, and formatting -whenever you save a file, to make things easy. +To auto-format your Java and Kotlin code from the command line, you can run `./gradlew spotlessApply`. +We recommend installing support for spotless in your IDE, and formatting +whenever you save a file to make things easy. -If you need to prevent autoformatting for a particular region of code, use +If you need to prevent autoformatting for a select region of code, use `// @formatter:off` and `// @formatter:on` -### Setting up spotless in VSCode +#### Setting up spotless for IntelliJ IDEA +* Install https://plugins.jetbrains.com/plugin/18321-spotless-gradle +* Add a keyboard shortcut for `Code` > `Reformat Code with Spotless` +* They are working on support to do this on save without a keybind + [here](https://github.com/ragurney/spotless-intellij-gradle/issues/8) + +#### Setting up spotless for VSCode * Install the `richardwillis.vscode-spotless-gradle` extension * Add the following to your workspace settings, at `.vscode/settings.json`: ```json @@ -55,13 +71,7 @@ If you need to prevent autoformatting for a particular region of code, use } ``` -### Setting up spotless for IntelliJ -* Install https://plugins.jetbrains.com/plugin/18321-spotless-gradle. -* Add a keyboard shortcut for `Code` > `Reformat Code with Spotless` -* They are working on support to do this on save without a keybind -[here](https://github.com/ragurney/spotless-intellij-gradle/issues/8) - -### Setting up Eclipse autoformatting +#### Setting up Eclipse autoformatting Import the formatting settings defined in `spotless.xml`, like this: * Go to `File > Properties`, then `Java Code Style > Formatter` * Check `Enable project specific settings` @@ -73,19 +83,31 @@ Import the formatting settings defined in `spotless.xml`, like this: Eclipse will only do a subset of the checks in `spotless`, so you may still want to do `./gradlew spotlessApply` if you ever see an error from spotless. -### Version bumping -* Add new release inside ```` in the ``dev.slimevr.SlimeVR.metainfo.xml`` file. (Example: ``https://github.com/SlimeVR/SlimeVR-Server/releases/tag/va.b.c``) -* Create the git tag instead of making it from releases, you can do it by just ``git tag VERSION``, - example ``git tag v0.5.0`` -* You need to push this change with ``git push origin VERSION`` or ``git push origin --tags`` -(will push all tags you made). +### Tauri (gui) -We recommend committing first and then making the tag, that tag will point to the commit you are currently -on. +We use ESLint and Prettier to format GUI code. +- First, go into the GUI's directory with your terminal by running `cd gui`. +- To check code formatting, run `npm run lint`. +- To fix code formatting, run `npm run lint:fix` and `npm run format` + +Don't forget to run `cd ..` to return to the root directory. + +## SolarXR Protocol + +SolarXR is used to communicate between the server (backend) and GUI (frontend). +It can also be used to communicate to third party applications. + +When touching SolarXR: +- You will need `flatc`. To know which version to get, refer to +[SolarXR's README](https://github.com/SlimeVR/SolarXR-Protocol/blob/main/README.md#flatc) +- The only files you should edit are in the `schema` directory. +- After editing files, you should run `cd solarxr-protocol`, then either run +`./generate-flatbuffer.ps1` (Windows) or `./generate-flatbuffer.sh` (Linux/OSX) +- Make sure to commit your changes inside the submodule. ## Code Licensing SlimeVR uses dual MIT and Apache-2.0 license. Be sure that any code that you reference, -or dependencies you add, are compatible with these licenses. `GPL-v3` for example is +or dependencies you add, are compatible with these licenses. For example, `GPL-v3` is not compatible because it requires any and all code that depends on it to *also* be licensed under `GPL-v3`. diff --git a/README.md b/README.md index 4734052da..bca857d48 100644 --- a/README.md +++ b/README.md @@ -9,20 +9,24 @@ Sensors implementations: * [SlimeVR Wrangler](https://github.com/carl-anders/slimevr-wrangler) - use Nintendo Switch Joycon controllers as trackers Integrations: -* Use [SlimeVR OpenVR Driver](https://github.com/SlimeVR/SlimeVR-OpenVR-Driver) as a driver for SteamVR -* Use built-in OSC support for integration with other apps, such as VRChat, using OSC -* Integrations with other systems will be added later +* Use [SlimeVR OpenVR Driver](https://github.com/SlimeVR/SlimeVR-OpenVR-Driver) as a driver for SteamVR. +* Use built-in OSC Trackers support for FBT integration with VRChat, PCVR or Standalone. +* Use built-in VMC support for sending and receiving tracking data to and from other apps such as VSeeFace. +* Export recordings as .BVH files to integrate motion capture data into 3d applications such as Blender. -## How to use +## Installing It's highly recommended to install using the installer downloadable here: https://github.com/SlimeVR/SlimeVR-Installer/releases/latest/download/slimevr_web_installer.exe -Latest setup instructions are [on our site](https://docs.slimevr.dev/server/index.html). +Latest setup instructions are [in our docs](https://docs.slimevr.dev/server/index.html). + +## Building & Contributing +For information on building and contributing to the codebase, see [CONTRIBUTING.md](CONTRIBUTING.md). ## License clarification **SlimeVR software** (including server, firmware, drivers, installer, documents, and others - see licence for each case specifically) **is distributed under a dual MIT/Apache 2.0 License ([LICENSE-MIT] and [LICENSE-APACHE]). The software is the copyright of the SlimeVR -contributors.** +contributors.** **However, these licenses have some limits, and if you wish to distribute software based on SlimeVR, you need to be aware of them:** @@ -54,7 +58,5 @@ You also certify that the code you have used is compatible with those licenses o authored by you. If you're doing so on your work time, you certify that your employer is okay with this and that you are authorized to provide the above licenses. -For a how-to on contributing, see [CONTRIBUTING.md](CONTRIBUTING.md). - [LICENSE-MIT]: LICENSE-MIT [LICENSE-APACHE]: LICENSE-APACHE diff --git a/gui/LICENSE.md b/gui/LICENSE.md deleted file mode 100644 index 9ac0ec176..000000000 --- a/gui/LICENSE.md +++ /dev/null @@ -1,6 +0,0 @@ -This directory and all subdirectories are dual-licensed under either - -* MIT License ([/LICENSE-MIT](/LICENSE-MIT)) -* Apache License, Version 2.0 ([/LICENSE-APACHE](/LICENSE-APACHE)) - -at your option. diff --git a/gui/README.md b/gui/README.md deleted file mode 100644 index 194cea087..000000000 --- a/gui/README.md +++ /dev/null @@ -1,30 +0,0 @@ -# SlimeVR UI - -This is the GUI of SlimeVR, it uses the SolarXR protocol to communicate with the server and is completely isolated from the server logic. - -This project is written in Typescript + React for the frontend and uses Tauri + Rust as a small backend. This makes the application more lightweight than electron. - -## Compiling - -### Prerequisites - -- [Node.js](https://nodejs.org) 16 (We recommend the use of `nvm` instead of installing Node.js directly) -- Windows Webview -- SlimeVR server installed -- [Rust](https://rustup.rs) - -``` -npm install -``` - -Build for production - -``` -npm run tauri build -``` - -Launch in dev mode - -``` -npm run tauri dev -```