README-jack-server.txt

This documentation describes usage of Jack server 1.3-a8.

Jack server
===========

The Jack server's goal is to handle a pool of Jack compiler instances in
order to limit memory usage and benefit from already warm instances.

Setup for Mac OS
----------------

Jack server is automatically installed and started by android build but
requires initial setup on Mac OS:

-   Install MacPorts from macports.org  
     Make sure that /opt/local/bin appears in your path before /usr/bin.
    If not, please add the following to your ~/.bash_profile file (If
    you do not have a .bash_profile file in your home directory, create
    one):

            export PATH=/opt/local/bin:$PATH`

-   Get curl package from MacPorts:

            $ POSIXLY_CORRECT=1 sudo port install curl +ssl

Starting the server
-------------------

You may need to start the Jack server manually.  
Use jack-admin start-server.

Client info
-----------

The client is a bash script simply named jack.  
It can be configured in $HOME/.jack-settings

.jack-settings file

This file contains script shell variables:  
SERVER_HOST: IP address of the server  
by default: SERVER_HOST=127.0.0.1.

SERVER_PORT_SERVICE: Server service TCP port number. Needs to match the
service port number defined in $HOME/.jack-server/config.properties on
the server host (See Server info below)  
by default: SERVER_PORT_SERVICE=8076.

SERVER_PORT_ADMIN: Server admin TCP port number. Needs to match the
admin port number defined in $HOME/.jack-server/config.properties on the
server host (See Server info below)  
by default: SERVER_PORT_ADMIN=8077.

SETTING_VERSION: Internal, do not modify.

Server info
-----------

The server is composed of 2 jars named jack-server.jar and
jack-launcher.jar.

Check Admin section to know how to install and administrate the Jack
server.

The server can also be configured in
$HOME/.jack-server/config.properties.

config.properties file

It contains Jack server configuration properties.  
Modifications to those settings are taken into account after restarting
the server.  
Description with default values follows:

jack.server.max-service=<number>  
 Maximum number of simultaneous Jack tasks. Default is 4.

jack.server.max-jars-size=<size-in-bytes>  
 Maximum size for Jars, in bytes. -1 means no limit. Default is 100 MiB.

jack.server.time-out=<time-in-seconds>  
 Time out delay before Jack gets to sleep. When Jack sleeps, its memory
usage is reduced, but it is slower to wake up. -1 means "do not sleep".
Default is 2 weeks.

jack.server.service.port=<port-number>  
 Server service TCP port number. Default is 8076. Needs to match the
service port defined in $HOME/.jack-settings on the client host (See
Client section).

jack.server.admin.port=<port-number>  
 Server admin TCP port number. Default is 8077. Needs to match the
service port defined in $HOME/.jack-settings on the client host (See
Client section).

jack.server.config.version=<version>  
 Internal, do not modify.

Server logs

Server logs can be found by running jack-admin server-log. Default
location is $HOME/.jack-server/logs/.

Admin
-----

The jack-admin bash script allows to install and administrate the Jack
server. Here are some commands:

$ jack-admin help  
Print help.

$ jack-admin install-server jack-launcher.jar jack-server.jar  
Install the Jack server.

$ jack-admin uninstall-server  
Uninstall the Jack server and all components.

$ jack-admin list jack  
List installed versions for Jack.

$ jack-admin update jack jack.jar  
Install or update a Jack jar.

$ jack-admin start-server  
Start the server.

$ jack-admin stop-server  
Stop the server after the last compilation is complete.

$ jack-admin kill-server  
Kill the server process immediately, interrupting abruptly ongoing
compilations.

$ jack-admin list-server  
List Jack server processes.

$ jack-admin server-stat  
Print various info about the server and the host.

$ jack-admin server-log  
Print log pattern.

$ jack-admin dump-report  
Produce a report file that can be used to file a bug.

Transitioning from server 1.1 (e.g. Marshmallow) to server 1.3 (e.g. N)
-----------------------------------------------------------------------

The old Jack server used a $HOME/.jack configuration file. It has now
replaced by a $HOME/.jack-settings and a
$HOME/.jack-server/config.properties. If those new files do not exist,
run jack-admin start-server and they will be created. If you had custom
settings in your $HOME/.jack, here's how to adapt those.

SERVER_PORT_SERVICE=XXXX  
Replace with SERVER_PORT_SERVICE=XXXX in $HOME/.jack-settings and
jack.server.service.port=XXXX in $HOME/.jack-server/config.properties.

SERVER_PORT_ADMIN=YYYY  
Replace with SERVER_PORT_ADMIN=YYYY in $HOME/.jack-settings and
jack.server.admin.port=YYYY in $HOME/.jack-server/config.properties.

SERVER_NB_COMPILE=N  
Replace with jack.server.max-service=N in
$HOME/.jack-server/config.properties.

SERVER_TIMEOUT=ZZ  
You can replace with jack.server.time-out=ZZ, but it is recommended to
keep the default setting of "7200" (2 hours).

Other settings in the $HOME/.jack configuration file do not need to be
copied. You should still keep your $HOME/.jack configuration file for
the old Jack server because both server versions can run simultaneously.

Troubleshooting
---------------

Below you'll find some ways to solve some troubleshooting. If you don't
find a solution, file a bug and attach the file produced by
jack-admin dump-report.

If compilation fails on No Jack server running

See Starting the server above.

If your computer becomes unresponsive during compilation:

You can improve the situation by reducing the number of jack
simultaneous compilations by editing your
$HOME/.jack-server/config.properties and changing
jack.server.max-service to a lower value and then restarting the server.

If you experience Jack compilations failing on Out of memory error.:

You can improve the situation by reducing the number of jack
simultaneous compilations by editing your
$HOME/.jack-server/config.properties and changing
jack.server.max-service to a lower value and then restarting the
server.  
If this is not enough, you may change the arguments used to start the
server jvm and force a greater maximum Java heap size ("-Xmx"):  
- Stop the server using jack-admin stop-server, then:  
- If you start the server manually:  
JACK_SERVER_VM_ARGUMENTS="-Xmx2g -Dfile.encoding=UTF-8 -XX:+TieredCompilation" jack-admin start-server  
- If you use the jack server in the android tree then  
export ANDROID_JACK_VM_ARGS="-Xmx2g -Dfile.encoding=UTF-8 -XX:+TieredCompilation"  
and restart your build command.

If you have trouble starting the server

This may mean that TCP ports are already in use on your computer. You
can try modifying the ports both in your client and server
configurations. See the Server info and Client info sections. If it
doesn't solve the problem, please report and give us additional
information by:  
 - Attaching your compilation log.  
 - Attaching the file produced by jack-admin dump-report

If your commands fails on

Failed to contact Jack server: Problem reading<your home>/.jack-server/client.pem

This may mean that your server never managed to start, see If you have
trouble starting the server above.

If your compilation gets stuck without any progress

Please report and give us additional information by attaching the file
produced by jack-admin dump-report.  
Then restart the server by issuing commands
jack-admin kill-server; jack-admin start-server