.. lblGettingStarted:

Initial Setup
=============

Installation
------------

The AMPL API can function as an add-on to any existing AMPL installation.
If you do not yet have an AMPL installation on the computer where you will
be working with the API, see our
`demo page <http://ampl.com/try-ampl/download-a-free-demo/>`_ or
`trial page <http://ampl.com/try-ampl/request-a-full-trial/>`_ to download a
working version that can be installed quickly.

Follow the instructions on our `AMPL API <http://ampl.com/products/api/>`_
page to download the API package appropriate to your platform, and to add
the downloaded folder (directory) ``amplapi`` to your AMPL installation.

Initial test
------------

Be sure that you have a valid JDK installation (release 1.6 or later)
accessible. If necessary you can `download
<http://www.oracle.com/technetwork/java/javase/downloads/jdk7-downloads-1880260.html>`_
the latest release.

To make an initial test, open a command/terminal window and make
``amplapi/examples/java`` the current folder (directory). Then enter the
following commands to compile and then run a simple example:

Windows:

.. parsed-literal::

   set PATH=%CD%/../../bin/;%PATH%
   javac -cp ../../lib/|ampl_jar_raw| FirstExample.java
   java -cp ../../lib/|ampl_jar_raw|;. FirstExample <solver>

Linux:

.. parsed-literal::

   export LD_LIBRARY_PATH=$PWD/../../lib:$LD_LIBRARY_PATH
   javac -cp ../../lib/|ampl_jar_raw| FirstExample.java
   java -cp ../../lib/|ampl_jar_raw|:. FirstExample <solver>

macOS:

.. parsed-literal::

   javac -cp ../../lib/|ampl_jar_raw| FirstExample.java
   java -Djava.library.path=../../lib -cp ../../lib/|ampl_jar_raw|:. FirstExample <solver>

where optionally ``<solver>`` is the name of a solver that has been installed with AMPL.
(If a solver is not specified, AMPL’s default choice will be used.) Alternatively,
compile and run ``FirstExample.java`` from your preferred Java IDE with
|ampl_jar| included in the class path. This will solve several small diet
problems and then display the optimal amounts of the foods from the last
solution.

Note that the folder containing the AMPL executable should be in the system search path.
Otherwise, the error message "AMPL could not be started" will be shown.
If the AMPL installation directory is not in the system search path,
you can add it passing a new :java:ref:`Environment` to :java:ref:`AMPL` as follows:

.. code-block:: java

  Environment env = new Environment("full path to the AMPL installation directory");
  AMPL ampl = new AMPL(env);

Note that you may need to escape backslashes (e.g., `"C:\\\\ampl\\\\ampl.mswin64"`) if included in the path.

Development
-----------

Reference |ampl_jar_full| in your project that uses the AMPL API. Together with
your existing AMPL implementation, this will provide the full object library
and access to all AMPL functions. The binary files that must be accessible are
platform dependent and listed below, using the main amplapi directory as root:

* Windows:
    * ``bin\javaswigwrapper.dll``
    * |ampl_so_win|

* Linux
    * ``lib/libjavaswigwrapper.so``
    * |ampl_so_linux|

* macOS:
    * ``lib/libjavaswigwrapper.jnilib``
    * |ampl_so_osx|

The ``amplapi`` folder (directory) can be moved to a different location in your
computer’s filesystem, provided that the location of your AMPL executable has
been placed in the system search path.

Deployment
----------

To deploy AMPL API applications to users who do not have their own AMPL
installations, include with your Java application the AMPL executable
(``ampl`` or ``ampl.exe``), the additional files listed in the previous section,
the binaries needed to run any solvers that are used and
an appropriate license file for AMPL and solvers.