mirror of https://git.tuxpa.in/a/code-server.git
Docs copyedits: README.md + CONTRIBUTING.md (#2242)
* Edit README * Edit CONTRIBUTING * Format CONTRIBUTING.MD * Incorporate feedback * Revert movement of CONTRIBUTING.MD and format
This commit is contained in:
parent
7e1e9d1249
commit
860c99e3b8
46
README.md
46
README.md
|
@ -6,72 +6,58 @@ Run [VS Code](https://github.com/Microsoft/vscode) on any machine anywhere and a
|
||||||
|
|
||||||
## Highlights
|
## Highlights
|
||||||
|
|
||||||
- **Code everywhere**
|
- Code on any device with a consistent development environment
|
||||||
- Code on your Chromebook, tablet, and laptop with a consistent development environment.
|
- Use cloud servers to speed up tests, compilations, downloads, and more
|
||||||
- Develop on a Linux machine and pick up from any device with a web browser.
|
- Preserve battery life when you're on the go; all intensive tasks run on your server
|
||||||
- **Server-powered**
|
|
||||||
- Take advantage of large cloud servers to speed up tests, compilations, downloads, and more.
|
|
||||||
- Preserve battery life when you're on the go as all intensive tasks run on your server.
|
|
||||||
- Make use of a spare computer you have lying around and turn it into a full development environment.
|
|
||||||
|
|
||||||
## Getting Started
|
## Getting Started
|
||||||
|
|
||||||
For a full setup and walkthrough, please see [./doc/guide.md](./doc/guide.md).
|
There are two ways to get started:
|
||||||
|
|
||||||
### Quick Install
|
1. Using the [install script](./install.sh), which automates most of the process. The script uses the system package manager (if possible)
|
||||||
|
2. Manually installing code-server; see [Installation](./doc/install.md) for instructions applicable to most use cases
|
||||||
|
|
||||||
We have a [script](./install.sh) to install code-server for Linux, macOS and FreeBSD.
|
If you choose to use the install script, you can preview what occurs during the install process:
|
||||||
|
|
||||||
It tries to use the system package manager if possible.
|
|
||||||
|
|
||||||
First run to print out the install process:
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
curl -fsSL https://code-server.dev/install.sh | sh -s -- --dry-run
|
curl -fsSL https://code-server.dev/install.sh | sh -s -- --dry-run
|
||||||
```
|
```
|
||||||
|
|
||||||
Now to actually install:
|
To install, run:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
curl -fsSL https://code-server.dev/install.sh | sh
|
curl -fsSL https://code-server.dev/install.sh | sh
|
||||||
```
|
```
|
||||||
|
|
||||||
The install script will print out how to run and start using code-server.
|
When done, the install script prints out instructions for running and starting code-server.
|
||||||
|
|
||||||
### Manual Install
|
We also have an in-depth [setup and configuration](./doc/guide.md) guide.
|
||||||
|
|
||||||
Docs on the install script, manual installation and docker image are at [./doc/install.md](./doc/install.md).
|
|
||||||
|
|
||||||
### Alpha Program 🐣
|
### Alpha Program 🐣
|
||||||
|
|
||||||
We're working on a cloud platform to make deploying and managing code-server easier. If you don't want to worry about
|
We're working on a cloud platform that makes deploying and managing code-server easier. Consider [joining our alpha program](https://codercom.typeform.com/to/U4IKyv0W) if you don't want to worry about
|
||||||
|
|
||||||
- TLS
|
- TLS
|
||||||
- Authentication
|
- Authentication
|
||||||
- Port Forwarding
|
- Port Forwarding
|
||||||
|
|
||||||
consider [joining our alpha program](https://codercom.typeform.com/to/U4IKyv0W).
|
|
||||||
|
|
||||||
## FAQ
|
## FAQ
|
||||||
|
|
||||||
See [./doc/FAQ.md](./doc/FAQ.md).
|
See [./doc/FAQ.md](./doc/FAQ.md).
|
||||||
|
|
||||||
## Contributing
|
## Want to help?
|
||||||
|
|
||||||
See [./doc/CONTRIBUTING.md](./doc/CONTRIBUTING.md).
|
See [CONTRIBUTING](./doc/CONTRIBUTING.md) for details.
|
||||||
|
|
||||||
## Hiring
|
## Hiring
|
||||||
|
|
||||||
We ([@cdr](https://github.com/cdr)) are looking for engineers to help maintain
|
We ([@cdr](https://github.com/cdr)) are looking for engineers to help [maintain
|
||||||
code-server, innovate on open source and streamline dev workflows.
|
code-server](https://jobs.lever.co/coder/e40becde-2cbd-4885-9029-e5c7b0a734b8), innovate on open source, and streamline dev workflows.
|
||||||
|
|
||||||
Our main office is in Austin, Texas. Remote is ok as long as
|
Our main office is in Austin, Texas. Remote is ok as long as
|
||||||
you're in North America or Europe.
|
you're in North America or Europe.
|
||||||
|
|
||||||
Please get in [touch](mailto:jobs@coder.com) with your resume/github if interested.
|
Please get in [touch](mailto:jobs@coder.com) with your resume/GitHub if interested.
|
||||||
|
|
||||||
We're also hiring someone specifically to help maintain code-server.
|
|
||||||
See the listing [here](https://jobs.lever.co/coder/e40becde-2cbd-4885-9029-e5c7b0a734b8).
|
|
||||||
|
|
||||||
## For Organizations
|
## For Organizations
|
||||||
|
|
||||||
|
|
|
@ -8,6 +8,7 @@
|
||||||
- [Build](#build)
|
- [Build](#build)
|
||||||
- [Structure](#structure)
|
- [Structure](#structure)
|
||||||
- [VS Code Patch](#vs-code-patch)
|
- [VS Code Patch](#vs-code-patch)
|
||||||
|
- [Currently Known Issues](#currently-known-issues)
|
||||||
|
|
||||||
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
|
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
|
||||||
|
|
||||||
|
@ -15,24 +16,26 @@
|
||||||
|
|
||||||
## Pull Requests
|
## Pull Requests
|
||||||
|
|
||||||
Please link to the issue each PR solves.
|
Please create a [GitHub Issue](https://github.com/cdr/code-server/issues) for each issue
|
||||||
If there is no existing issue, please first create one unless the fix is minor.
|
you'd like to address unless the proposed fix is minor.
|
||||||
|
|
||||||
Please make sure the base of your PR is the master branch. We keep the GitHub
|
In your Pull Requests (PR), link to the issue that the PR solves.
|
||||||
default branch the latest release branch to avoid confusion as the
|
|
||||||
documentation is on GitHub and we don't want users to see docs on unreleased
|
Please ensure that the base of your PR is the **master** branch. (Note: The default
|
||||||
features.
|
GitHub branch is the latest release branch, though you should point all of your changes to be merged into
|
||||||
|
master).
|
||||||
|
|
||||||
## Requirements
|
## Requirements
|
||||||
|
|
||||||
Please refer to [VS Code's prerequisites](https://github.com/Microsoft/vscode/wiki/How-to-Contribute#prerequisites).
|
The prerequisites for contributing to code-server are almost the same as those for
|
||||||
|
[VS Code](https://github.com/Microsoft/vscode/wiki/How-to-Contribute#prerequisites).
|
||||||
|
There are several differences, however. You must:
|
||||||
|
|
||||||
Differences:
|
- Use Node.js version 12.x (or greater)
|
||||||
|
- Have [nfpm](https://github.com/goreleaser/nfpm) (which is used to build `.deb` and `.rpm` packages and [jq](https://stedolan.github.io/jq/) (used to build code-server releases) installed
|
||||||
|
|
||||||
- We require a minimum of node v12 but later versions should work.
|
The [CI container](../ci/images/debian8/Dockerfile) is a useful reference for all
|
||||||
- We use [nfpm](https://github.com/goreleaser/nfpm) to build `.deb` and `.rpm` packages.
|
of the dependencies code-server uses.
|
||||||
- We use [jq](https://stedolan.github.io/jq/) to build code-server releases.
|
|
||||||
- The [CI container](../ci/images/debian10/Dockerfile) is a useful reference for all our dependencies.
|
|
||||||
|
|
||||||
## Development Workflow
|
## Development Workflow
|
||||||
|
|
||||||
|
@ -40,10 +43,10 @@ Differences:
|
||||||
yarn
|
yarn
|
||||||
yarn vscode
|
yarn vscode
|
||||||
yarn watch
|
yarn watch
|
||||||
# Visit http://localhost:8080 once the build completed.
|
# Visit http://localhost:8080 once the build is completed.
|
||||||
```
|
```
|
||||||
|
|
||||||
To develop inside of an isolated docker container:
|
To develop inside an isolated Docker container:
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
./ci/dev/image/run.sh yarn
|
./ci/dev/image/run.sh yarn
|
||||||
|
@ -53,12 +56,12 @@ To develop inside of an isolated docker container:
|
||||||
|
|
||||||
`yarn watch` will live reload changes to the source.
|
`yarn watch` will live reload changes to the source.
|
||||||
|
|
||||||
If changes are made to the patch and you've built previously you must manually
|
If you introduce changes to the patch and you've previously built, you
|
||||||
reset VS Code then run `yarn vscode:patch`.
|
must (1) manually reset VS Code and (2) run `yarn vscode:patch`.
|
||||||
|
|
||||||
## Build
|
## Build
|
||||||
|
|
||||||
You can build with:
|
You can build using:
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
./ci/dev/image/run.sh ./ci/steps/release.sh
|
./ci/dev/image/run.sh ./ci/steps/release.sh
|
||||||
|
@ -66,22 +69,22 @@ You can build with:
|
||||||
|
|
||||||
Run your build with:
|
Run your build with:
|
||||||
|
|
||||||
```
|
```shell
|
||||||
cd release
|
cd release
|
||||||
yarn --production
|
yarn --production
|
||||||
# Runs the built JavaScript with Node.
|
# Runs the built JavaScript with Node.
|
||||||
node .
|
node .
|
||||||
```
|
```
|
||||||
|
|
||||||
Build release packages (make sure you run `./ci/steps/release.sh` first):
|
Build the release packages (make sure that you run `./ci/steps/release.sh` first):
|
||||||
|
|
||||||
```
|
```shell
|
||||||
IMAGE=centos7 ./ci/dev/image/run.sh ./ci/steps/release-packages.sh
|
IMAGE=centos7 ./ci/dev/image/run.sh ./ci/steps/release-packages.sh
|
||||||
# The standalone release is in ./release-standalone
|
# The standalone release is in ./release-standalone
|
||||||
# .deb, .rpm and the standalone archive are in ./release-packages
|
# .deb, .rpm and the standalone archive are in ./release-packages
|
||||||
```
|
```
|
||||||
|
|
||||||
The `release.sh` script is the equivalent of:
|
The `release.sh` script is equal to running:
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
yarn
|
yarn
|
||||||
|
@ -91,73 +94,69 @@ yarn build:vscode
|
||||||
yarn release
|
yarn release
|
||||||
```
|
```
|
||||||
|
|
||||||
And `release-packages.sh` is:
|
And `release-packages.sh` is equal to:
|
||||||
|
|
||||||
```
|
```shell
|
||||||
yarn release:standalone
|
yarn release:standalone
|
||||||
yarn test:standalone-release
|
yarn test:standalone-release
|
||||||
yarn package
|
yarn package
|
||||||
```
|
```
|
||||||
|
|
||||||
For a faster release build you can also run:
|
For a faster release build, you can run instead:
|
||||||
|
|
||||||
```
|
```shell
|
||||||
KEEP_MODULES=1 ./ci/steps/release.sh
|
KEEP_MODULES=1 ./ci/steps/release.sh
|
||||||
node ./release
|
node ./release
|
||||||
```
|
```
|
||||||
|
|
||||||
## Structure
|
## Structure
|
||||||
|
|
||||||
The `code-server` script serves an HTTP API to login and start a remote VS Code process.
|
The `code-server` script serves an HTTP API for login and starting a remote VS Code process.
|
||||||
|
|
||||||
The CLI code is in [./src/node](./src/node) and the HTTP routes are implemented in
|
The CLI code is in [./src/node](./src/node) and the HTTP routes are implemented in
|
||||||
[./src/node/app](./src/node/app).
|
[./src/node/app](./src/node/app).
|
||||||
|
|
||||||
Most of the meaty parts are in our VS Code patch which is described next.
|
Most of the meaty parts are in the VS Code patch, which we described next.
|
||||||
|
|
||||||
### VS Code Patch
|
### VS Code Patch
|
||||||
|
|
||||||
Back in v1 of code-server, we had an extensive patch of VS Code that split the codebase
|
In v1 of code-server, we had a patch of VS Code that split the codebase into a front-end
|
||||||
into a frontend and server. The frontend consisted of all UI code and the server ran
|
and a server. The front-end consisted of all UI code, while the server ran the extensions
|
||||||
the extensions and exposed an API to the frontend for file access and everything else
|
and exposed an API to the front-end for file access and all UI needs.
|
||||||
that the UI needed.
|
|
||||||
|
|
||||||
This worked but eventually Microsoft added support to VS Code to run it in the web.
|
Over time, Microsoft added support to VS Code to run it on the web. They have made
|
||||||
They have open sourced the frontend but have kept the server closed source.
|
the front-end open source, but not the server. As such, code-server v2 (and later) uses
|
||||||
|
the VS Code front-end and implements the server. You can find this in
|
||||||
So in interest of piggy backing off their work, v2 and beyond use the VS Code
|
|
||||||
web frontend and fill in the server. This is contained in our
|
|
||||||
[./ci/dev/vscode.patch](../ci/dev/vscode.patch) under the path `src/vs/server`.
|
[./ci/dev/vscode.patch](../ci/dev/vscode.patch) under the path `src/vs/server`.
|
||||||
|
|
||||||
Other notable changes in our patch include:
|
Other notable changes in our patch include:
|
||||||
|
|
||||||
- Add our own build file which includes our code and VS Code's web code.
|
- Adding our build file, which includes our code and VS Code's web code
|
||||||
- Allow multiple extension directories (both user and built-in).
|
- Allowing multiple extension directories (both user and built-in)
|
||||||
- Modify the loader, websocket, webview, service worker, and asset requests to
|
- Modifying the loader, websocket, webview, service worker, and asset requests to
|
||||||
use the URL of the page as a base (and TLS if necessary for the websocket).
|
use the URL of the page as a base (and TLS, if necessary for the websocket)
|
||||||
- Send client-side telemetry through the server.
|
- Sending client-side telemetry through the server
|
||||||
- Allow modification of the display language.
|
- Allowing modification of the display language
|
||||||
- Make it possible for us to load code on the client.
|
- Making it possible for us to load code on the client
|
||||||
- Make extensions work in the browser.
|
- Making extensions work in the browser
|
||||||
- Make it possible to install extensions of any kind.
|
- Making it possible to install extensions of any kind
|
||||||
- Fix getting permanently disconnected when you sleep or hibernate for a while.
|
- Fixing issue with getting disconnected when your machine sleeps or hibernates
|
||||||
- Add connection type to web socket query parameters.
|
- Adding connection type to web socket query parameters
|
||||||
|
|
||||||
Some known issues presently:
|
As the web portion of VS Code matures, we'll be able to shrink and possibly
|
||||||
|
eliminate our patch. In the meantime, upgrading the VS Code version requires
|
||||||
- Creating custom VS Code extensions and debugging them doesn't work.
|
us to ensure that the patch is applied and works as intended. In the future,
|
||||||
- Extension profiling and tips are currently disabled.
|
we'd like to run VS Code unit tests against our builds to ensure that features
|
||||||
|
|
||||||
As the web portion of VS Code matures, we'll be able to shrink and maybe even entirely
|
|
||||||
eliminate our patch. In the meantime, however, upgrading the VS Code version requires
|
|
||||||
ensuring that the patch still applies and has the intended effects.
|
|
||||||
|
|
||||||
To generate a new patch run `yarn vscode:diff`.
|
|
||||||
|
|
||||||
**note**: We have extension docs on the CI and build system at [./ci/README.md](../ci/README.md)
|
|
||||||
|
|
||||||
If functionality doesn't depend on code from VS Code then it should be moved
|
|
||||||
into code-server otherwise it should be in the patch.
|
|
||||||
|
|
||||||
In the future we'd like to run VS Code unit tests against our builds to ensure features
|
|
||||||
work as expected.
|
work as expected.
|
||||||
|
|
||||||
|
To generate a new patch, run `yarn vscode:diff`
|
||||||
|
|
||||||
|
**Note**: We have [extension docs](../ci/README.md) on the CI and build system.
|
||||||
|
|
||||||
|
If the functionality you're working on does NOT depend on code from VS Code, please
|
||||||
|
move it out and into code-server.
|
||||||
|
|
||||||
|
### Currently Known Issues
|
||||||
|
|
||||||
|
- Creating custom VS Code extensions and debugging them doesn't work
|
||||||
|
- Extension profiling and tips are currently disabled
|
||||||
|
|
Loading…
Reference in New Issue