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