This repository has been archived by the owner on Mar 26, 2024. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 126
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Move documentation to a dedicated site
- Loading branch information
Showing
4 changed files
with
5 additions
and
213 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,121 +1 @@ | ||
| # The Projector for JetBrains IDE | ||
|
|
||
| The Projector is a technology for rendering IDE GUI over the network. It should be compatible with all existing JetBrains IDEs. | ||
|
|
||
|
|
||
| ## Use cases | ||
|
|
||
| 1. Running the code from IDE located near the runtime (whatever it is) or near the database to reduce roundtrips; | ||
| 2. High-security zones and corporate environments; | ||
| 3. Really huge projects; | ||
| 4. No source code on a laptop; | ||
| 5. Slow or hot users’ laptops; | ||
| 6. Thin clients and cheap hardware like Android tablets; | ||
| 7. Running the IDE in a GNU/Linux environment on Windows machines or even on exotic operating systems like ChromeOS; | ||
| 8. The ability to turn off your computer, while your app continues to work on the server; | ||
| 9. Slow internet connection; | ||
| 10. Remote debugging on a server-side (devtest, devprod); | ||
| 11. VM or Docker images with debug sources and pre-configured IDE. | ||
| 12. Any configuration that requires remote access. | ||
|
|
||
|  | ||
|
|
||
| *IntelliJ IDEA on Android tablet (Huawei MediaPad M5)* | ||
|
|
||
|
|
||
| ## The state of the Projector | ||
|
|
||
| Currently, it is in a private preview stage. Please evaluate it and send your feedback to the Projector team. Your feedback is vital for understanding the Projector's future and prototyping its new features. | ||
|
|
||
| You can report any issues here:[ https://youtrack.jetbrains.com/issues/PRJ](https://youtrack.jetbrains.com/issues/PRJ) \ | ||
| Feel free to report any bug or submit a feature request: every single opinion is important. | ||
|
|
||
|
|
||
| ## Where to start | ||
|
|
||
| The easiest way to try the project is to use Docker Images. Here's the repo:[ https://github.com/JetBrains/projector-docker](https://github.com/JetBrains/projector-docker) | ||
|
|
||
| If you can't use Docker for some reasons (for example, due to any security limitations), try this installation script:[ https://github.com/JetBrains/projector-installer](https://github.com/JetBrains/projector-installer) | ||
|
|
||
| If you can't even use this installation script, you need to dive deeper and understand how it works under the hood. You can check README here:[ https://github.com/JetBrains/projector-server/](https://github.com/JetBrains/projector-server/) | ||
|
|
||
| As for the client-side, just open the URL (something like [https://127.0.0.1:8887](https://127.0.0.1:8887)) in the browser, and that’s it. | ||
|
|
||
|
|
||
| ## Client-side | ||
|
|
||
| Currently, you can use a web browser to connect to the IDE. The experience is very similar to using any interactive website. You can use a fullscreen mode in your browser to achieve an almost desktop-like experience. | ||
|
|
||
| If the technology preview is considered successful, and if there is a demand from users, in the next stages we may build separate native applications. | ||
|
|
||
|
|
||
| ## Server-side | ||
|
|
||
| You can use the Projector as a set of Docker images, or as a standalone distribution. A standalone distribution is currently available for GNU/Linux hosts only. | ||
|
|
||
| Dockerfiles are public and Open Source, so you can verify them with your security team. | ||
|
|
||
|
|
||
| ## VPN and SSH tunnels | ||
|
|
||
| The Projector should run on popular VPN solutions like OpenVPN. It uses the HTTP and WebSocket protocols to connect to the browser. You shouldn't have any problems with that. | ||
|
|
||
| Also, you can use the following SSH command to redirect these ports through a plain SSH tunnel : | ||
|
|
||
| ``` | ||
| ssh -i key.pem -L 8887:127.0.0.1:8887 user@server | ||
| ``` | ||
|
|
||
| You can try this on the Amazon cloud. | ||
|
|
||
|
|
||
| ## Competitors | ||
|
|
||
| The сlosest competitors to the Projector are X Window System, VNC, and RDP. | ||
|
|
||
| One the one hand, the Projector is much more responsive. Unlike all these alternatives, it uses extended and precise information about applications written in Java (which all JetBrains IDEs are) and sends it over the network. For example, that allows rendering crisp, pixel-perfect vector fonts. And it doesn't matter if your connection is slow or not, your text always is perfect, because the fonts are all in a vector format. | ||
|
|
||
| On the other hand, X11, VNC, and RDP are well-known solutions, and system administrators know exactly how to run them in a corporate environment. | ||
|
|
||
|
|
||
| ## Is it Open Source? | ||
|
|
||
| Now, everything is an Open Source or Free Software: | ||
|
|
||
| * Dockerfiles (Apache License 2.0):[ https://github.com/JetBrains/projector-docker](https://github.com/JetBrains/projector-docker) | ||
| * Server (GNU GPL v2.0):[ https://github.com/JetBrains/projector-server.git](https://github.com/JetBrains/projector-server.git) | ||
| * Client (MIT License):[ https://github.com/JetBrains/projector-client.git](https://github.com/JetBrains/projector-client.git) | ||
|
|
||
|
|
||
| ## Known problems | ||
|
|
||
| The server side is supported as a Docker Image and as a local distribution for Linux servers. Local installations of the server on Windows and Mac are not a subject for the preview stage of the project. However, technically it is quite possible. | ||
|
|
||
| We still have some inconsistencies in shortcuts. For example, a known problem is that we cannot use Ctrl+W to close a source file, because it closes a tab in the browser. The only action Projector can do here is to ask the user if they really want to close that tab. In the future, we can create separate native apps instead of the browser client to fix this. | ||
|
|
||
| There's a known limitation on using plugins with a custom rendering provided by Chromium Embedded Framework because it bypasses the standard rendering pipeline in Java. It's a hard problem, probably we can fix this, but not at an early preview stage. Now we have a smart workaround for the Markdown component: we render Markdown HTML locally on a client. Actually, it even improved the experience of writing markdown a lot. | ||
|
|
||
| We cannot render separate external applications. For example, if you run the Android Emulator by activating a Run/Debug configuration, and expect to see GUI, it's impossible to render it with the Projector. In the future, it may be solved by combining with VNC technologies, but it's definitely not a target of the preview stage. | ||
|
|
||
|
|
||
| ## What's new | ||
|
|
||
| The following improvements have been added recently: | ||
|
|
||
| * An improved protocol: | ||
| * Before this change, parsing the protocol took four times longer than rendering. After the change it should be ten times faster; | ||
| * That's all about the client-side. This change does nothing with the data transfer part of the pipeline; | ||
| * Better graphics performance: | ||
| * Improved bitmap image deduplication significantly reduced the network load; | ||
| * Image caching algorithms and two-pass rendering eliminated freezes on a client-side; | ||
| * Better support on mobile devices: | ||
| * On-screen keyboard button; | ||
| * Functional keys; | ||
| * Touch interfaces — we're testing it right now. | ||
| * Multiple projects inside a single IDE: | ||
| * A separate URL for each project; | ||
| * API for managing tabs may come later; | ||
| * A command-line interface for quick installation: | ||
| * Using a single command to start the server and output the URL for connection; | ||
| * You can pick an IDE from a pre-populated list or specify the location on your local storage; | ||
| * Updated scripts for the modern IntelliJ IDEA versions. | ||
| This document is moved to [documentation](https://jetbrains.github.io/projector-client/mkdocs/latest/). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,22 +1,5 @@ | ||
| # Contributing to Projector | ||
| Thank you for reading this: we welcome any contributions. | ||
|
|
||
| All Projector-related projects have the same contributing guidelines. This is the place where they are described. | ||
|
|
||
| ## Creating an issue | ||
| You can create issues in our [issue tracker](https://youtrack.jetbrains.com/issues/PRJ). | ||
|
|
||
| If you **report a bug**, please either describe reproduction steps or mention that you don't know how to reproduce it stably. You can also **suggest a feature**. | ||
|
|
||
| If you've found the same ticket, please avoid creating a duplicate. | ||
|
|
||
| ## Submitting changes | ||
| If you want to resolve an **issue submitted in the issue tracker** or propose a **minor edit**, open a Pull Request. Better don't include multiple changes in a single PR, create separate. | ||
|
|
||
| **Pre-commit actions**. Before committing, please ensure that code style is correct. If you use IntelliJ IDEA, you can just select the following checkboxes of "Before Commit" actions: | ||
| * Reformat code | ||
| * Rearrange code | ||
| * Optimize imports | ||
| * Cleanup | ||
|
|
||
| **Commits naming**. If there are issues that you address, please mention them in the prefix of commit messages. Usually, a commit name starts with a verb. Example: `PRJ-68 Make clipboard owners lose ownership when clipboard is changed by a client`. | ||
| All Projector-related projects have the same contributing guidelines. The place where they are described | ||
| is [documentation](https://jetbrains.github.io/projector-client/mkdocs/latest/about/contributing/). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,72 +1 @@ | ||
| # Projector | ||
| This document describes the ecosystem as a whole. | ||
|
|
||
| ## TL;DR | ||
| Projector is a way to run Swing applications without any windowing system and accessing them either locally or remotely. | ||
|
|
||
| If you seek for clear info of how this can be practically used, we advise you to read [README-JETBRAINS.md](../README-JETBRAINS.md) about accessing remotely run JetBrains IDEs. | ||
|
|
||
| ## The system | ||
| Here you can find some info on how this works. | ||
|
|
||
| ### AWT implementation | ||
| The Foundation stone of Projector is an implementation of AWT. It allows running Swing applications headlessly but without `HeadlessException`s. Also, it intercepts some AWT calls and remembers them. The most calls are invocations of `Graphics2D` methods. This module is called `projector-awt`. | ||
|
|
||
| ### Server and client | ||
| To run an application with our AWT and access it, we provide a server and a client. | ||
|
|
||
| The module of the server implementation is called `projector-server`. It provides a launcher that sets AWT system properties and fields and is compatible with the most of Swing apps. | ||
|
|
||
| Also, it extracts remembered AWT calls from `projector-awt` and can send them on a client. This implementation uses WebSocket and a serialization protocol which is located in the `projector-common` module. A client can execute the received calls on its side. The only client implemented now is for Web browsers, it's available in the `projector-client-web` module. | ||
|
|
||
| Finally, the client can send its events such as mouse clicks or window resizes in the reverse direction. `projector-server` translates these events to AWT. | ||
|
|
||
| ### Client components | ||
| Some Swing apps contain content that can't be easily represented as `Graphics2D` method calls. For example, it can be an embedded heavyweight component. In such cases, it's sometimes possible to serialize this content another way. | ||
|
|
||
| The only client component implemented now is Markdown Preview in JetBrains IDEs. | ||
|
|
||
| ## Repositories | ||
| Here we enumerate repos related to this project and describe their content. | ||
|
|
||
| ### Main | ||
| * [projector-client](https://github.com/JetBrains/projector-client): | ||
| * `projector-common` — protocol and other common code for clients and a server. | ||
| * `projector-client-common` — common code for clients. | ||
| * `projector-client-web` — a client implementation for Web browsers. | ||
| * [projector-server](https://github.com/JetBrains/projector-server): | ||
| * `projector-awt` — AWT implementation. | ||
| * `projector-server` — an application server for running and remote accessing a Swing app. | ||
|
|
||
| ### Examples and utils | ||
| * [projector-demo](https://github.com/JetBrains/projector-demo) — a sample app showing how to run any Swing app with Projector. | ||
| * [projector-docker](https://github.com/JetBrains/projector-docker) — scripts for building Docker images containing JetBrains IDEs, Projector Server, and a web server hosting Web Client inside. | ||
| * [projector-installer](https://github.com/JetBrains/projector-installer) — a utility for installing, configuring, and running JetBrains IDEs with `projector-server` on Linux or in WSL, available at PyPI. | ||
|
|
||
| ### Obsolete | ||
| * [projector-markdown-plugin](https://github.com/JetBrains/projector-markdown-plugin) — Markdown Preview for JetBrains IDEs which can be used with Projector. Now we managed to bundle it to projector-server, so you don't need to install it separately anymore. | ||
|
|
||
| ## How to use | ||
| You can find some hints in the corresponding repos. | ||
|
|
||
| You can use [JitPack](https://jitpack.io/) to make a dependency on our project. Also, you can clone a project and build it yourself. | ||
|
|
||
| We show these ways in example repos. | ||
|
|
||
| ## Use cases | ||
| We believe there are many cases when you may want to use Projector. Let's enumerate some of them to inspire you: | ||
| * Not running a Swing IDE on a high-end laptop, but running it on a server and accessing it via a **thin client**: | ||
| * Usually, **high-end laptops cost more** than a server with comparable performance and a thin client. | ||
| * A thin client not only has a relatively small price but also it **doesn't contain any valuable data**, so a case of its loss is not a big deal. | ||
| * Thin clients are **more mobile**: you aren't restricted to use only x86, you can select ARM and devices that are cooler, more compact, and have longer battery life, for example, you can use iPad and a keyboard instead of MacBook. | ||
| * Not **remote debugging** in a local Swing IDE, but accessing a remote Swing IDE doing local debugging. | ||
| * Not **coding in nano or vim over ssh** but copying a Swing IDE and Projector there and access it. | ||
| * Run your Swing IDE in a **Linux environment but on Windows**: you can simply run it via Projector Server in WSL and use a client in Windows. This is easier than other methods such as installing X Server to WSL or using a visual virtual machine. | ||
| * Do **pair programming** sessions remotely: multiple clients can simultaneously connect to the same Swing IDE and interact with it in rotation. | ||
| * You can **turn your device off** while your app continues work on a server. For example, if your project is so huge that it takes a night to compile it fully, you can leave this task for a server and take your device with you without risk of overheating in your bag. | ||
|
|
||
| ## Comparison to other remote access solutions | ||
| Here we formulate the pros of Projector: | ||
| * Since our goal is to support only AWT apps, Projector is **more compact** than more general remote access software like RDP or VNC. You don't even have to install special apps anywhere: on a server-side, you need only JRE, but there is one because your app is a Java app; on a client-side, you need only a Web browser, and you have it on almost any device. | ||
| * Since Projector Server knows about **AWT components**, some of them can be serialized in a special way to be shown on a client **natively**. The example is the Markdown Preview of JetBrains IDEs. | ||
| * Projector supports **simultaneous client connections** to the same application instance. | ||
| This document is moved to [documentation](https://jetbrains.github.io/projector-client/mkdocs/latest/). |