From f5d317e2ab2bab575f6b1e6d32106952d01ede91 Mon Sep 17 00:00:00 2001 From: crschnick Date: Thu, 5 Oct 2023 11:53:52 +0000 Subject: [PATCH] Update readmes --- CONTRIBUTING.md | 59 ++++++++++++++++++++++++++++++++++++++++++++++--- DEVELOPMENT.md | 55 --------------------------------------------- FAQ.md | 2 +- README.md | 17 +++++++------- 4 files changed, 66 insertions(+), 67 deletions(-) delete mode 100644 DEVELOPMENT.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c1b324af..e2e331e5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,8 +1,61 @@ -# Contributors guide +# Development -If you're interested in contributing to XPipe, you can easily do so! Just submit a pull request with your changes. +Any contribution is welcomed! +There are no real formal contribution guidelines right now, they will maybe come later. + +## Repository Structure + +- [core](core) - Shared core classes of the XPipe Java API, XPipe extensions, and the XPipe daemon implementation. + This mainly concerns API classes not a lot of implementation. +- [beacon](beacon) - The XPipe beacon component is responsible for handling all communications between the XPipe + daemon and the client applications, for example APIs and the CLI +- [app](app) - Contains the XPipe daemon implementation, the XPipe desktop application, and an + API to create all different kinds of extensions for the XPipe platform +- [dist](dist) - Tools to create a distributable package of XPipe +- [ext](ext) - Available XPipe extensions. Essentially every concrete feature implementation is implemented as an extension + +## Modularity + +All XPipe components target [Java 21](https://openjdk.java.net/projects/jdk/20/) and make full use of the Java Module System (JPMS). +All components are modularized, including all their dependencies. +In case a dependency is (sadly) not modularized yet, module information is manually added using [moditect](https://github.com/moditect/moditect-gradle-plugin). +Further, note that as this is a pretty complicated Java project that fully utilizes modularity, +many IDEs still have problems building this project properly. + +For example, you can't build this project in eclipse or vscode as it will complain about missing modules. +The tested and recommended IDE is IntelliJ. +When setting up the project in IntelliJ, make sure that the correct JDK (Java 20) +is selected both for the project and for gradle itself. + +## Setup + +You need to have an up-to-date version of XPipe installed on your local system in order to properly +run XPipe in a development environment. +This is due to the fact that some components are only included in the release version and not in this repository. +XPipe is able to automatically detect your local installation and fetch the required +components from it when it is run in a development environment. + +You need to have GraalVM Community Edition for Java 21 installed as a JDK to compile the project. +If you are on Linux or macOS, you can easily accomplish that by running the `setup.sh` script. +On Windows, you have to manually install the JDK. + +## Building and Running + +You can use the gradle wrapper to build and run the project: +- `gradlew app:run` will run the desktop application. You can set various useful properties in `app/build.gradle` +- `gradlew dist` will create a distributable production version in `dist/build/dist/base`. +- `gradlew :test` will run the tests of the specified project. + +You are also able to properly debug the built production application through two different methods: +- The `dist/build/dist/base/app/scripts/xpiped_debug` script will launch the application in debug mode and with a console attached to it +- The `dist/build/dist/base/app/scripts/xpiped_debug_attach` script attaches a debugger with the help of [AttachMe](https://plugins.jetbrains.com/plugin/13263-attachme). + Just make sure that the attachme process is running within IntelliJ, and the debugger should launch automatically once you start up the application. + +Note that when any unit test is run using a debugger, the XPipe daemon process that is started will also attempt +to connect to that debugger through [AttachMe](https://plugins.jetbrains.com/plugin/13263-attachme) as well. + +## Contributing guide -In terms of development environment setup, be sure to read the [development page](https://github.com/xpipe-io/xpipe/blob/master/DEVELOPMENT.md) first. Especially when starting out, it might be a good idea to start with easy tasks first. Here's a selection of suitable common tasks that are very easy to implement: ### Implementing support for a new editor diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md deleted file mode 100644 index aee8b5e8..00000000 --- a/DEVELOPMENT.md +++ /dev/null @@ -1,55 +0,0 @@ -# Development - -Any contribution is welcomed! -There are no real formal contribution guidelines right now, they will maybe come later. - -## Repository Structure - -- [core](core) - Shared core classes of the XPipe Java API, XPipe extensions, and the XPipe daemon implementation. - This mainly concerns API classes not a lot of implementation. -- [beacon](beacon) - The XPipe beacon component is responsible for handling all communications between the XPipe - daemon and the client applications, for example APIs and the CLI -- [app](app) - Contains the XPipe daemon implementation, the XPipe desktop application, and an - API to create all different kinds of extensions for the XPipe platform -- [dist](dist) - Tools to create a distributable package of XPipe -- [ext](ext) - Available XPipe extensions. Essentially every concrete feature implementation is implemented as an extension - -## Modularity - -All XPipe components target [Java 20](https://openjdk.java.net/projects/jdk/20/) and make full use of the Java Module System (JPMS). -All components are modularized, including all their dependencies. -In case a dependency is (sadly) not modularized yet, module information is manually added using [moditect](https://github.com/moditect/moditect-gradle-plugin). -Further, note that as this is a pretty complicated Java project that fully utilizes modularity, -many IDEs still have problems building this project properly. - -For example, you can't build this project in eclipse or vscode as it will complain about missing modules. -The tested and recommended IDE is IntelliJ. -When setting up the project in IntelliJ, make sure that the correct JDK (Java 20) -is selected both for the project and for gradle itself. - -## Setup - -You need to have an up-to-date version of XPipe installed on your local system in order to properly -run XPipe in a development environment. -This is due to the fact that some components are only included in the release version and not in this repository. -XPipe is able to automatically detect your local installation and fetch the required -components from it when it is run in a development environment. - -You need to have GraalVM Community Edition for Java 20 installed as a JDK to compile the project. -If you are on Linux or macOS, you can easily accomplish that by running the `setup.sh` script. -On Windows, you have to manually install the JDK. - -## Building and Running - -You can use the gradle wrapper to build and run the project: -- `gradlew app:run` will run the desktop application. You can set various useful properties in `app/build.gradle` -- `gradlew dist` will create a distributable production version in `dist/build/dist/base`. -- `gradlew :test` will run the tests of the specified project. - -You are also able to properly debug the built production application through two different methods: -- The `dist/build/dist/base/app/scripts/xpiped_debug` script will launch the application in debug mode and with a console attached to it -- The `dist/build/dist/base/app/scripts/xpiped_debug_attach` script attaches a debugger with the help of [AttachMe](https://plugins.jetbrains.com/plugin/13263-attachme). - Just make sure that the attachme process is running within IntelliJ, and the debugger should launch automatically once you start up the application. - -Note that when any unit test is run using a debugger, the XPipe daemon process that is started will also attempt -to connect to that debugger through [AttachMe](https://plugins.jetbrains.com/plugin/13263-attachme) as well. diff --git a/FAQ.md b/FAQ.md index 3a1426d2..21d2a287 100644 --- a/FAQ.md +++ b/FAQ.md @@ -89,7 +89,7 @@ The professional version also comes with a feature to synchronize your storage w ## Can I contribute to this project? -Yes, check out the [development page](/DEVELOPMENT.md) for details on how to set up a development environment and the [contributing page](/CONTRIBUTING.md) on how to get started. +Yes, check out the [contribution page](/CONTRIBUTING.md) for details. ## Why are there no GitHub actions workflows in this repository? diff --git a/README.md b/README.md index f9bbe1e5..d6cf8df0 100644 --- a/README.md +++ b/README.md @@ -86,12 +86,6 @@ This script will automatically install the `.msi` for you. powershell -ExecutionPolicy Bypass -Command iwr "https://raw.githubusercontent.com/xpipe-io/xpipe/master/get-xpipe.ps1" -OutFile "$env:TEMP\get-xpipe.ps1" ";" "&" "$env:TEMP\get-xpipe.ps1" ``` -If you like chocolatey, you can also install the [xpipe choco package](https://community.chocolatey.org/packages/xpipe): - -``` -choco install xpipe -``` - #### Linux / MacOS The script supports installation via `apt`, `rpm`, and `pacman` on Linux, plus a `.pkg` install on macOS: @@ -100,7 +94,14 @@ The script supports installation via `apt`, `rpm`, and `pacman` on Linux, plus a bash <(curl -sL https://raw.githubusercontent.com/xpipe-io/xpipe/master/get-xpipe.sh) ``` -Alternatively on arch, the [xpipe AUR package](https://aur.archlinux.org/packages/xpipe) can also be installed via `yay -S xpipe`. + +### Package managers + +Alternatively, you can also use your favorite package manager (if supported): + +- [choco](https://community.chocolatey.org/packages/xpipe): `choco install xpipe` +- [AUR package](https://aur.archlinux.org/packages/xpipe): `yay -S xpipe` +- [Homebrew](https://github.com/xpipe-io/homebrew-tap): `brew install --cask xpipe-io/tap/xpipe` ## Commercial usage @@ -121,7 +122,7 @@ For information about the security model of XPipe, see the [security page](/SECU For information about the privacy policy of XPipe, see the [privacy page](/PRIVACY.md). -In case you're interested in development, check out the [development page](/DEVELOPMENT.md). +In case you're interested in development, check out the [contributing page](/CONTRIBUTING.md). If you want to talk you can also join: