1 This documentation describes usage of Jack server 1.3-a8. 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 is automatically installed and started by android build but requires initial setup on 13 Mac OS: 14 15 - Install MacPorts from [macports.org](http://www.macports.org/install.php) 16 Make sure that `/opt/local/bin appears` in your path before `/usr/bin`. If not, please 17 add the following to your `~/.bash_profile` file (If you do not have a `.bash_profile` 18 file in your home directory, create one): 19 ``` 20 export PATH=/opt/local/bin:$PATH` 21 ``` 22 23 - Get curl package from MacPorts: 24 ``` 25 $ POSIXLY_CORRECT=1 sudo port install curl +ssl 26 ``` 27 28 ## Starting the server 29 30 You may need to start the Jack server manually. 31 Use `jack-admin start-server`. 32 33 34 35 ## Client info 36 37 The client is a bash script simply named `jack`. 38 It can be configured in `$HOME/.jack-settings` 39 40 41 42 ### `.jack-settings` file 43 44 This file contains script shell variables: 45 `SERVER_HOST`: IP address of the server 46 by default: `SERVER_HOST=127.0.0.1`. 47 48 `SERVER_PORT_SERVICE`: Server service TCP port number. Needs to match the service port 49 number defined in `$HOME/.jack-server/config.properties` on the server host 50 (See **Server info** below) 51 by default: `SERVER_PORT_SERVICE=8076`. 52 53 `SERVER_PORT_ADMIN`: Server admin TCP port number. Needs to match the admin port number 54 defined in `$HOME/.jack-server/config.properties` on the server host (See **Server info** below) 55 by default: `SERVER_PORT_ADMIN=8077`. 56 57 `SETTING_VERSION`: Internal, do not modify. 58 59 60 61 ## Server info 62 63 The server is composed of 2 jars named `jack-server.jar` and `jack-launcher.jar`. 64 65 Check `Admin` section to know how to install and administrate the Jack server. 66 67 The server can also be configured in `$HOME/.jack-server/config.properties`. 68 69 70 71 ### `config.properties` file 72 73 It contains Jack server configuration properties. 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 usage is reduced, but it is 84 slower to wake up. `-1` means "do not sleep". Default is 2 weeks. 85 86 `jack.server.service.port=<port-number>` 87 Server service TCP port number. Default is 8076. Needs to match the service port defined in 88 `$HOME/.jack-settings` on the client host (See Client section). 89 90 `jack.server.admin.port=<port-number>` 91 Server admin TCP port number. Default is 8077. Needs to match the service port defined in 92 `$HOME/.jack-settings` on the client host (See Client section). 93 94 `jack.server.config.version=<version>` 95 Internal, do not modify. 96 97 98 99 ### Server logs 100 101 Server logs can be found by running `jack-admin server-log`. Default location is 102 `$HOME/.jack-server/logs/`. 103 104 105 106 ## Admin 107 108 The `jack-admin` bash script allows to install and administrate the Jack server. 109 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 compilations. 134 135 `$ jack-admin list-server` 136 List Jack server processes. 137 138 `$ jack-admin server-stat` 139 Print various info about the server and the host. 140 141 `$ jack-admin server-log` 142 Print log pattern. 143 144 `$ jack-admin dump-report` 145 Produce a report file that can be used to file a bug. 146 147 148 ## Transitioning from server 1.1 (e.g. Marshmallow) to server 1.3 (e.g. N) 149 150 The old Jack server used a `$HOME/.jack` configuration file. It has now replaced by a 151 `$HOME/.jack-settings` and a `$HOME/.jack-server/config.properties`. 152 If those new files do not exist, run `jack-admin start-server` and they will be created. 153 If you had custom settings in your `$HOME/.jack`, here's how to adapt those. 154 155 `SERVER_PORT_SERVICE=XXXX` 156 Replace with `SERVER_PORT_SERVICE=XXXX` in `$HOME/.jack-settings` and 157 `jack.server.service.port=XXXX` in `$HOME/.jack-server/config.properties`. 158 159 `SERVER_PORT_ADMIN=YYYY` 160 Replace with `SERVER_PORT_ADMIN=YYYY` in `$HOME/.jack-settings` and 161 `jack.server.admin.port=YYYY` in `$HOME/.jack-server/config.properties`. 162 163 `SERVER_NB_COMPILE=N` 164 Replace with `jack.server.max-service=N` in `$HOME/.jack-server/config.properties`. 165 166 `SERVER_TIMEOUT=ZZ` 167 You can replace with `jack.server.time-out=ZZ`, but it is recommended to keep the default setting of 168 "7200" (2 hours). 169 170 Other settings in the `$HOME/.jack` configuration file do not need to be copied. 171 You should still keep your `$HOME/.jack` configuration file for the old Jack server because both 172 server versions can run simultaneously. 173 174 175 ## Troubleshooting 176 177 Below you'll find some ways to solve some troubleshooting. If you don't find a solution, file a 178 bug and attach the file produced by `jack-admin dump-report`. 179 180 181 ### If compilation fails on `No Jack server running` 182 183 See [Starting the server](#starting-the-server) above. 184 185 186 ### If your computer becomes unresponsive during compilation or if you experience Jack compilations 187 failing on `Out of memory error.`: 188 189 You can improve the situation by reducing the number of jack simultaneous compilations by editing 190 your `$HOME/.jack-server/config.properties` and changing jack.server.max-service to a lower value. 191 192 193 ### If you have trouble starting the server 194 195 This may mean that TCP ports are already in use on your computer. You can try modifying the ports 196 both in your client and server configurations. See the `Server info` and `Client info` sections. 197 If it doesn't solve the problem, please report and give us additional information by: 198 - Attaching your compilation log. 199 - Attaching the file produced by `jack-admin dump-report` 200 201 202 ### If your commands fails on 203 `Failed to contact Jack server: Problem reading<your home>/.jack-server/client.pem` 204 205 This may mean that your server never managed to start, see 206 [If you have trouble starting the server](#if-you-have-trouble-starting-the-server) above. 207 208 209 ### If your compilation gets stuck without any progress 210 211 Please report and give us additional information by attaching the file produced by 212 `jack-admin dump-report`. 213 Then restart the server by issuing commands `jack-admin kill-server; jack-admin start-server` 214 215
