diff options
Diffstat (limited to 'subprojects/docs/versioned_docs/version-0.1.0/develop/contributing/commands.md')
-rw-r--r-- | subprojects/docs/versioned_docs/version-0.1.0/develop/contributing/commands.md | 158 |
1 files changed, 158 insertions, 0 deletions
diff --git a/subprojects/docs/versioned_docs/version-0.1.0/develop/contributing/commands.md b/subprojects/docs/versioned_docs/version-0.1.0/develop/contributing/commands.md new file mode 100644 index 00000000..7ffe2a6c --- /dev/null +++ b/subprojects/docs/versioned_docs/version-0.1.0/develop/contributing/commands.md | |||
@@ -0,0 +1,158 @@ | |||
1 | --- | ||
2 | SPDX-FileCopyrightText: 2024 The Refinery Authors | ||
3 | SPDX-License-Identifier: EPL-2.0 | ||
4 | sidebar_position: 1 | ||
5 | title: Build commands | ||
6 | --- | ||
7 | |||
8 | # Building from the command line | ||
9 | |||
10 | ## Gradle commands | ||
11 | |||
12 | We use [Gradle](https://gradle.org/) to manage the compilation and tests of Refinery. | ||
13 | |||
14 | Java code is built directly by Gradle. | ||
15 | We use the [frontend-gradle-plugin](https://siouan.github.io/frontend-gradle-plugin/) to manage a [Node.js](https://nodejs.org/en) and [Yarn](https://yarnpkg.com/) installation, which in turn is used to build TypeScript code (including this documentation website). | ||
16 | Typically, Yarn commands are issued by Gradle and you don't need to work with the TypeScript build system directly if you're only working on the Java parts of Refinery. | ||
17 | |||
18 | ### `build` | ||
19 | |||
20 | ```bash posix2windows | ||
21 | ./gradlew build | ||
22 | ``` | ||
23 | |||
24 | Compile all code, run all tests, and produce all build artifacts. | ||
25 | |||
26 | You should run this command before submitting a [Pull request](https://github.com/graphs4value/refinery/pulls) to make sure that all code builds and tests pass on your local machine. | ||
27 | This will also be run by GitHub Actions for each commit or pull requests. | ||
28 | |||
29 | ### `publishToMavenLocal` | ||
30 | |||
31 | ```bash posix2windows | ||
32 | ./gradlew publishToMavenLocal | ||
33 | ``` | ||
34 | |||
35 | Publishes the Refinery Java artifacts to the [Maven local repository](https://www.baeldung.com/maven-local-repository). | ||
36 | |||
37 | Build tools, such as Gradle, will be able to consume such artifacts, which enables you to use the latest version of Refinery -- possibly including your own modifications -- in other Java projects. | ||
38 | For more information, see our [programming guide](/snapshot/develop/java). | ||
39 | |||
40 | ### `serve` | ||
41 | |||
42 | ```bash posix2windows | ||
43 | ./gradlew serve | ||
44 | ``` | ||
45 | |||
46 | Starts the Refinery backend and web interface on port 1312. | ||
47 | |||
48 | This task is ideal for running the Refinery backend if you don't intend to work on the frontend. | ||
49 | The Refinery frontend TypeScript projects is automatically built before the server starts. | ||
50 | The server will use the latest build output of the frontend as static assets. | ||
51 | |||
52 | The behavior of this task is influenced by the same [environmental variables](../../../learn/docker#environmental-variables) as the Refinery [Docker container](../../../learn/docker). | ||
53 | However, the default value of `REFINERY_LISTEN_PORT` is `1312`. | ||
54 | |||
55 | ### `serveBackend` | ||
56 | |||
57 | ```bash posix2windows | ||
58 | ./gradlew serveBackend | ||
59 | ``` | ||
60 | |||
61 | Starts the Refinery backend on port 1312. | ||
62 | |||
63 | This task is ideal for running the Refinery backend if you're working on the frontend. | ||
64 | No static assets will be build. | ||
65 | You'll need to use [`yarnw frontend dev`](#frontend-dev) | ||
66 | |||
67 | Like [`./gradlew serve`](#serve), the behavior of this task is influenced by the same [environmental variables](../../../learn/docker#environmental-variables) as the Refinery [Docker container](../../../learn/docker). | ||
68 | However, the default value of `REFINERY_LISTEN_PORT` is `1312`. | ||
69 | |||
70 | ## Yarn commands | ||
71 | |||
72 | We provide a `yarnw` wrapper script to invoke the Yarn distribution installed by frontend-gradle-plugin directly. | ||
73 | The following commands can only be run once [`./gradlew build`](#build) has installed the necessary Node.js and Yarn packages. | ||
74 | |||
75 | ### `docs dev` | ||
76 | |||
77 | ```bash posix2windows | ||
78 | ./yarnw docs dev | ||
79 | ``` | ||
80 | |||
81 | Builds and serves this documentation in development mode on port 3000. | ||
82 | Saved changes to most documentation sources are immediately reflected in the browse without reloading. | ||
83 | |||
84 | You can set the port with the `-p` option, e.g. to use port 1313, use | ||
85 | |||
86 | ```bash posix2windows | ||
87 | ./yarnw docs dev -p 1313 | ||
88 | ``` | ||
89 | |||
90 | :::note | ||
91 | |||
92 | Running this command for the first time may generate error messages like | ||
93 | ``` | ||
94 | ERROR failed to read input source map: failed to parse inline source map url | ||
95 | ``` | ||
96 | which can be safely ignored. | ||
97 | |||
98 | ::: | ||
99 | |||
100 | ### `frontend dev` | ||
101 | |||
102 | ```bash posix2windows | ||
103 | ./yarnw frontend dev | ||
104 | ``` | ||
105 | |||
106 | Builds and serves the refinery frontend on port 1313. | ||
107 | Saved changes to most source files are immediately reflected in the browser without reload. | ||
108 | |||
109 | Before running this command, you need to start [`./gradlew serveBackend`](#servebackend) to provide a backend for the frontend to connect to. | ||
110 | The development server of the frontend will proxy all WebSocket connections to the backend. | ||
111 | |||
112 | The following environmental variables influence the behavior of this command: | ||
113 | |||
114 | #### `REFINERY_LISTEN_HOST` | ||
115 | |||
116 | Hostname to listen at for incoming HTTP connections. | ||
117 | |||
118 | **Default value:** `localhost` | ||
119 | |||
120 | #### `REFINERY_LISTEN_PORT` | ||
121 | |||
122 | TCP port to listen at for incoming HTTP connections. | ||
123 | |||
124 | **Default value:** `1313` | ||
125 | |||
126 | #### `REFINERY_BACKEND_HOST` | ||
127 | |||
128 | Hostname of the Refinery backend. | ||
129 | |||
130 | This should match the `REFINERY_LISTEN_HOST` passed to [`./gradlew serveBackend`](#servebackend). | ||
131 | |||
132 | **Default value:** `127.0.0.1` (connect to `localhost` over IPv4 only) | ||
133 | |||
134 | #### `REFINERY_LISTEN_PORT` | ||
135 | |||
136 | TCP port of the Refinery backend. | ||
137 | |||
138 | This should match the `REFINERY_LISTEN_PORT` passed to [`./gradlew serveBackend`](#servebackend). | ||
139 | |||
140 | **Default value:** `1312` | ||
141 | |||
142 | #### `REFINERY_PUBLIC_HOST` | ||
143 | |||
144 | Publicly visible hostname of the Refinery instance. | ||
145 | |||
146 | If you use a reverse proxy in front of the development server, you must set this variable. | ||
147 | Otherwise, connections to the development server will fail due to cross-origin protection. | ||
148 | |||
149 | **Default value:** equal to `REFINERY_LISTEN_HOST` | ||
150 | |||
151 | #### `REFINERY_PUBLIC_PORT` | ||
152 | |||
153 | Publicly visible port of the Refinery instance. | ||
154 | |||
155 | If you use a reverse proxy in front of the development server, you must set this variable. | ||
156 | Otherwise, connections to the development server will fail due to cross-origin protection. | ||
157 | |||
158 | **Default value:** equal to `REFINERY_LISTEN_PORT` | ||