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 Description with default values follows: 73 74 jack.server.max-service=<number> 75 Maximum number of simultaneous Jack tasks. Default is 4. 76 77 jack.server.max-jars-size=<size-in-bytes> 78 Maximum size for Jars, in bytes. -1 means no limit. Default is 100 MiB. 79 80 jack.server.time-out=<time-in-seconds> 81 Time out delay before Jack gets to sleep. When Jack sleeps, its memory 82 usage is reduced, but it is slower to wake up. -1 means "do not sleep". 83 Default is 2 weeks. 84 85 jack.server.service.port=<port-number> 86 Server service TCP port number. Default is 8076. Needs to match the 87 service port defined in $HOME/.jack-settings on the client host (See 88 Client section). 89 90 jack.server.admin.port=<port-number> 91 Server admin TCP port number. Default is 8077. Needs to match the 92 service port defined in $HOME/.jack-settings on the client host (See 93 Client section). 94 95 jack.server.config.version=<version> 96 Internal, do not modify. 97 98 Server logs 99 100 Server logs can be found by running jack-admin server-log. Default 101 location is $HOME/.jack-server/logs/. 102 103 Admin 104 ----- 105 106 The jack-admin bash script allows to install and administrate the Jack 107 server. Here are some commands: 108 109 $ jack-admin help 110 Print help. 111 112 $ jack-admin install-server jack-launcher.jar jack-server.jar 113 Install the Jack server. 114 115 $ jack-admin uninstall-server 116 Uninstall the Jack server and all components. 117 118 $ jack-admin list jack 119 List installed versions for Jack. 120 121 $ jack-admin update jack jack.jar 122 Install or update a Jack jar. 123 124 $ jack-admin start-server 125 Start the server. 126 127 $ jack-admin stop-server 128 Stop the server after the last compilation is complete. 129 130 $ jack-admin kill-server 131 Kill the server process immediately, interrupting abruptly ongoing 132 compilations. 133 134 $ jack-admin list-server 135 List Jack server processes. 136 137 $ jack-admin server-stat 138 Print various info about the server and the host. 139 140 $ jack-admin server-log 141 Print log pattern. 142 143 $ jack-admin dump-report 144 Produce a report file that can be used to file a bug. 145 146 Transitioning from server 1.1 (e.g. Marshmallow) to server 1.3 (e.g. N) 147 ----------------------------------------------------------------------- 148 149 The old Jack server used a $HOME/.jack configuration file. It has now 150 replaced by a $HOME/.jack-settings and a 151 $HOME/.jack-server/config.properties. If those new files do not exist, 152 run jack-admin start-server and they will be created. If you had custom 153 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 165 $HOME/.jack-server/config.properties. 166 167 SERVER_TIMEOUT=ZZ 168 You can replace with jack.server.time-out=ZZ, but it is recommended to 169 keep the default setting of "7200" (2 hours). 170 171 Other settings in the $HOME/.jack configuration file do not need to be 172 copied. You should still keep your $HOME/.jack configuration file for 173 the old Jack server because both server versions can run simultaneously. 174 175 Troubleshooting 176 --------------- 177 178 Below you'll find some ways to solve some troubleshooting. If you don't 179 find a solution, file a bug and attach the file produced by 180 jack-admin dump-report. 181 182 If compilation fails on No Jack server running 183 184 See Starting the server above. 185 186 If your computer becomes unresponsive during compilation or if you experience Jack compilations 187 188 failing on Out of memory error.: 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. 194 195 If you have trouble starting the server 196 197 This may mean that TCP ports are already in use on your computer. You 198 can try modifying the ports both in your client and server 199 configurations. See the Server info and Client info sections. If it 200 doesn't solve the problem, please report and give us additional 201 information by: 202 - Attaching your compilation log. 203 - Attaching the file produced by jack-admin dump-report 204 205 If your commands fails on 206 207 Failed to contact Jack server: Problem reading<your home>/.jack-server/client.pem 208 209 This may mean that your server never managed to start, see If you have 210 trouble starting the server above. 211 212 If your compilation gets stuck without any progress 213 214 Please report and give us additional information by attaching the file 215 produced by jack-admin dump-report. 216 Then restart the server by issuing commands 217 jack-admin kill-server; jack-admin start-server 218
