-
Notifications
You must be signed in to change notification settings - Fork 73
/
composing_applications.md
200 lines (156 loc) · 7.91 KB
/
composing_applications.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
---
title: Build your own IDE/Tool
---
# Build your own IDE/Tool
This guide will teach you how to build your own Theia-based application. The guide will demonstrate how to configure your own application composed of existing or new Theia extensions, and any VS Code extensions you want bundled in your application by default. Please get familiar with the [extension mechanisms of Theia](https://theia-ide.org/docs/extensions/) in case you are not already.
This guide describes the manual steps to build a Theia-based product, there are two ways to avoid this manual set-up:
- [Theia Extension Yeoman generator](https://github.com/eclipse-theia/generator-theia-extension): Generates Theia-based products along with example extensions.
- [Theia Blueprint](https://theia-ide.org/docs/blueprint_download/): A template tool for creating installable desktop applications based on Theia.
We still recommend reading the manual guide first, it allows you to understand the structure of a Theia-based project.
## Requirements
The detailed list of prerequisites is located at the main Theia repository:
- [Prerequisites](https://github.com/eclipse-theia/theia/blob/master/doc/Developing.md#prerequisites)
## Setup
Start with creating a new empty directory and moving into it:
mkdir my-app
cd my-app
Create `package.json` in this directory:
```json
{
"private": true,
"dependencies": {
"@theia/callhierarchy": "next",
"@theia/file-search": "next",
"@theia/git": "next",
"@theia/markers": "next",
"@theia/messages": "next",
"@theia/mini-browser": "next",
"@theia/navigator": "next",
"@theia/outline-view": "next",
"@theia/plugin-ext-vscode": "next",
"@theia/preferences": "next",
"@theia/preview": "next",
"@theia/search-in-workspace": "next",
"@theia/terminal": "next"
},
"devDependencies": {
"@theia/cli": "next"
}
}
```
In a nutshell, Theia applications and extensions are [Node.js packages](https://nodesource.com/blog/the-basics-of-package-json-in-node-js-and-npm/). Each package has a `package.json` file that manifests package metadata,
like `name`, `version`, its runtime and build time dependencies and so on.
Let's have a look at the created package:
- Its `name` and `version` are omitted since we are not going to use it as a dependency, and
it's marked as `private` since it is not going to be published as a Node.js package on its own.
- We've listed required extensions as runtime dependencies, e.g. `@theia/navigator`.
- Some extensions require additional tooling installed, in such cases, please consult the corresponding extension documentation.
- Use [this link](https://www.npmjs.com/search?q=keywords:theia-extension) to see all published extensions.
- We've listed [@theia/cli](https://www.npmjs.com/package/@theia/cli) as a build-time dependency. It provides scripts to build and run the application.
## Consuming VS Code Extensions
As part of your application, it is also possible to consume (and package) VS Code extensions.
The [Theia repository](https://github.com/eclipse-theia/theia/wiki/Consuming-Builtin-and-External-VS-Code-Extensions) contains a guide on how to
include such extensions as part of the application's `package.json`.
An example `package.json` may look like the following:
```json
{
"private": true,
"dependencies": {
"@theia/callhierarchy": "next",
"@theia/file-search": "next",
"@theia/git": "next",
"@theia/markers": "next",
"@theia/messages": "next",
"@theia/navigator": "next",
"@theia/outline-view": "next",
"@theia/plugin-ext-vscode": "next",
"@theia/preferences": "next",
"@theia/preview": "next",
"@theia/search-in-workspace": "next",
"@theia/terminal": "next",
"@theia/vsx-registry": "next"
},
"devDependencies": {
"@theia/cli": "next"
},
"scripts": {
"prepare": "yarn run clean && yarn build && yarn run download:plugins",
"clean": "theia clean",
"build": "theia build --mode development",
"start": "theia start --plugins=local-dir:plugins",
"download:plugins": "theia download:plugins"
},
"theiaPluginsDir": "plugins",
"theiaPlugins": {
"vscode-builtin-extensions-pack": "https://open-vsx.org/api/eclipse-theia/builtin-extension-pack/1.50.1/file/eclipse-theia.builtin-extension-pack-1.50.1.vsix"
},
"theiaPluginsExcludeIds": [
"ms-vscode.js-debug-companion",
"vscode.extension-editing",
"vscode.git",
"vscode.git-ui",
"vscode.github",
"vscode.github-authentication",
"vscode.microsoft-authentication"
]
}
```
The following properties are used to consume builtin plugins (bundled extensions):
- `theiaPluginsDir`: the relative path to deploy plugins into
- `theiaPlugins`: the collection of plugins to download (individual plugins or extension-packs) - can point to any valid download URL (ex: Open VSX, Github Releases, etc.)
- `theiaPluginsExcludeIds`: the list of plugin `ids` to exclude when resolving extension-packs
## Building
First, install all dependencies.
yarn
Second, use Theia CLI to build the application.
yarn theia build
`yarn` looks up `theia` executable provided by `@theia/cli` in the context of our application
and then executes the `build` command with `theia`.
This can take a while since the application is built in production mode by default,
i.e. obfuscated and minified.
## Running
After the build is finished, we can start the application:
yarn theia start --plugins=local-dir:plugins
or rely on the `start` script from `package.json`:
yarn start
You can provide a workspace path to open as a first argument
and `--hostname`, `--port` options to deploy the application on specific network interfaces and ports,
e.g. to open `/workspace` on all interfaces and port `8080`:
yarn start /my-workspace --hostname 0.0.0.0 --port 8080
In the terminal, you should see that Theia application is up and listening:
<img class="doc-image" src="/docs-terminal.png" alt="Terminal" style="max-width: 750px">
Open the application by entering the printed address in a new browser page.
## Troubleshooting
### Plugins not appearing
If no plugins are available in the running Theia instance, it may be that you need to tell Theia where to find the downloaded plugins.
The example above sets the `--plugins` switch in the `start` command which should be sufficient.
However if running `theia start` directly, you can alternatively set an environment variable to achieve the same thing:
export THEIA_DEFAULT_PLUGINS=local-dir:plugins
### Building native dependencies behind a proxy
If you run the `yarn` command behind a proxy you may encounter issues in building native dependencies (like `oniguruma`), in the last part of the build, with the following error stack:
[4/4] Building fresh packages...
[1/9] XXXXX
[2/9] XXXXX
[3/9] XXXXX
[4/9] XXXXX
error /theiaide/node_modules/XXXXX: Command failed.
Exit code: 1
Command: node-gyp rebuild
Arguments:
Directory: /theiaide/node_modules/XXXXX
Output:
gyp info it worked if it ends with ok
gyp info using [email protected]
gyp info using [email protected] | linux | x64
gyp http GET https://nodejs.org/download/release/v8.15.0/node-v8.15.0-headers.tar.gz
gyp WARN install got an error, rolling back install
gyp ERR! configure error
gyp ERR! stack Error: read ECONNRESET
gyp ERR! stack at TLSWrap.onread (net.js:622:25)
gyp ERR! System Linux 3.10.0-862.11.6.el7.x86_64
gyp ERR! command "/usr/bin/node" "/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js" "rebuild"
gyp ERR! cwd /theiaide/node_modules/XXXXX
gyp ERR! node -v v8.15.0
This happens because node-gyp does not rely on system/NPM proxy settings. In that case, download the `node-headers` file using the link provided in the error stack
(in the example above `https://nodejs.org/download/release/v8.15.0/node-v8.15.0-headers.tar.gz`) and run the build with the following command:
npm_config_tarball=/path/to/node-v8.15.0-headers.tar.gz yarn install