README-jack-server.txt
1 This documentation describes usage of Jack server 1.3-a8.
2
3 Jack server
4 ===========
5
6 The Jack server's goal is to handle a pool of Jack compiler instances in
7 order to limit memory usage and benefit from already warm instances.
8
9 Setup for Mac OS
10 ----------------
11
12 Jack server is automatically installed and started by android build but
13 requires initial setup on Mac OS:
14
15 - Install MacPorts from macports.org
16 Make sure that /opt/local/bin appears in your path before /usr/bin.
17 If not, please add the following to your ~/.bash_profile file (If
18 you do not have a .bash_profile file in your home directory, create
19 one):
20
21 export PATH=/opt/local/bin:$PATH`
22
23 - Get curl package from MacPorts:
24
25 $ POSIXLY_CORRECT=1 sudo port install curl +ssl
26
27 Starting the server
28 -------------------
29
30 You may need to start the Jack server manually.
31 Use jack-admin start-server.
32
33 Client info
34 -----------
35
36 The client is a bash script simply named jack.
37 It can be configured in $HOME/.jack-settings
38
39 .jack-settings file
40
41 This file contains script shell variables:
42 SERVER_HOST: IP address of the server
43 by default: SERVER_HOST=127.0.0.1.
44
45 SERVER_PORT_SERVICE: Server service TCP port number. Needs to match the
46 service port number defined in $HOME/.jack-server/config.properties on
47 the server host (See Server info below)
48 by default: SERVER_PORT_SERVICE=8076.
49
50 SERVER_PORT_ADMIN: Server admin TCP port number. Needs to match the
51 admin port number defined in $HOME/.jack-server/config.properties on the
52 server host (See Server info below)
53 by default: SERVER_PORT_ADMIN=8077.
54
55 SETTING_VERSION: Internal, do not modify.
56
57 Server info
58 -----------
59
60 The server is composed of 2 jars named jack-server.jar and
61 jack-launcher.jar.
62
63 Check Admin section to know how to install and administrate the Jack
64 server.
65
66 The server can also be configured in
67 $HOME/.jack-server/config.properties.
68
69 config.properties file
70
71 It contains Jack server configuration properties.
72 Modifications to those settings are taken into account after restarting
73 the server.
74 Description with default values follows:
75
76 jack.server.max-service=<number>
77 Maximum number of simultaneous Jack tasks. Default is 4.
78
79 jack.server.max-jars-size=<size-in-bytes>
80 Maximum size for Jars, in bytes. -1 means no limit. Default is 100 MiB.
81
82 jack.server.time-out=<time-in-seconds>
83 Time out delay before Jack gets to sleep. When Jack sleeps, its memory
84 usage is reduced, but it is slower to wake up. -1 means "do not sleep".
85 Default is 2 weeks.
86
87 jack.server.service.port=<port-number>
88 Server service TCP port number. Default is 8076. Needs to match the
89 service port defined in $HOME/.jack-settings on the client host (See
90 Client section).
91
92 jack.server.admin.port=<port-number>
93 Server admin TCP port number. Default is 8077. Needs to match the
94 service port defined in $HOME/.jack-settings on the client host (See
95 Client section).
96
97 jack.server.config.version=<version>
98 Internal, do not modify.
99
100 Server logs
101
102 Server logs can be found by running jack-admin server-log. Default
103 location is $HOME/.jack-server/logs/.
104
105 Admin
106 -----
107
108 The jack-admin bash script allows to install and administrate the Jack
109 server. Here are some commands:
110
111 $ jack-admin help
112 Print help.
113
114 $ jack-admin install-server jack-launcher.jar jack-server.jar
115 Install the Jack server.
116
117 $ jack-admin uninstall-server
118 Uninstall the Jack server and all components.
119
120 $ jack-admin list jack
121 List installed versions for Jack.
122
123 $ jack-admin update jack jack.jar
124 Install or update a Jack jar.
125
126 $ jack-admin start-server
127 Start the server.
128
129 $ jack-admin stop-server
130 Stop the server after the last compilation is complete.
131
132 $ jack-admin kill-server
133 Kill the server process immediately, interrupting abruptly ongoing
134 compilations.
135
136 $ jack-admin list-server
137 List Jack server processes.
138
139 $ jack-admin server-stat
140 Print various info about the server and the host.
141
142 $ jack-admin server-log
143 Print log pattern.
144
145 $ jack-admin dump-report
146 Produce a report file that can be used to file a bug.
147
148 Transitioning from server 1.1 (e.g. Marshmallow) to server 1.3 (e.g. N)
149 -----------------------------------------------------------------------
150
151 The old Jack server used a $HOME/.jack configuration file. It has now
152 replaced by a $HOME/.jack-settings and a
153 $HOME/.jack-server/config.properties. If those new files do not exist,
154 run jack-admin start-server and they will be created. If you had custom
155 settings in your $HOME/.jack, here's how to adapt those.
156
157 SERVER_PORT_SERVICE=XXXX
158 Replace with SERVER_PORT_SERVICE=XXXX in $HOME/.jack-settings and
159 jack.server.service.port=XXXX in $HOME/.jack-server/config.properties.
160
161 SERVER_PORT_ADMIN=YYYY
162 Replace with SERVER_PORT_ADMIN=YYYY in $HOME/.jack-settings and
163 jack.server.admin.port=YYYY in $HOME/.jack-server/config.properties.
164
165 SERVER_NB_COMPILE=N
166 Replace with jack.server.max-service=N in
167 $HOME/.jack-server/config.properties.
168
169 SERVER_TIMEOUT=ZZ
170 You can replace with jack.server.time-out=ZZ, but it is recommended to
171 keep the default setting of "7200" (2 hours).
172
173 Other settings in the $HOME/.jack configuration file do not need to be
174 copied. You should still keep your $HOME/.jack configuration file for
175 the old Jack server because both server versions can run simultaneously.
176
177 Troubleshooting
178 ---------------
179
180 Below you'll find some ways to solve some troubleshooting. If you don't
181 find a solution, file a bug and attach the file produced by
182 jack-admin dump-report.
183
184 If compilation fails on No Jack server running
185
186 See Starting the server above.
187
188 If your computer becomes unresponsive during compilation:
189
190 You can improve the situation by reducing the number of jack
191 simultaneous compilations by editing your
192 $HOME/.jack-server/config.properties and changing
193 jack.server.max-service to a lower value and then restarting the server.
194
195 If you experience Jack compilations failing on Out of memory error.:
196
197 You can improve the situation by reducing the number of jack
198 simultaneous compilations by editing your
199 $HOME/.jack-server/config.properties and changing
200 jack.server.max-service to a lower value and then restarting the
201 server.
202 If this is not enough, you may change the arguments used to start the
203 server jvm and force a greater maximum Java heap size ("-Xmx"):
204 - Stop the server using jack-admin stop-server, then:
205 - If you start the server manually:
206 JACK_SERVER_VM_ARGUMENTS="-Xmx2g -Dfile.encoding=UTF-8 -XX:+TieredCompilation" jack-admin start-server
207 - If you use the jack server in the android tree then
208 export ANDROID_JACK_VM_ARGS="-Xmx2g -Dfile.encoding=UTF-8 -XX:+TieredCompilation"
209 and restart your build command.
210
211 If you have trouble starting the server
212
213 This may mean that TCP ports are already in use on your computer. You
214 can try modifying the ports both in your client and server
215 configurations. See the Server info and Client info sections. If it
216 doesn't solve the problem, please report and give us additional
217 information by:
218 - Attaching your compilation log.
219 - Attaching the file produced by jack-admin dump-report
220
221 If your commands fails on
222
223 Failed to contact Jack server: Problem reading<your home>/.jack-server/client.pem
224
225 This may mean that your server never managed to start, see If you have
226 trouble starting the server above.
227
228 If your compilation gets stuck without any progress
229
230 Please report and give us additional information by attaching the file
231 produced by jack-admin dump-report.
232 Then restart the server by issuing commands
233 jack-admin kill-server; jack-admin start-server
234