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