.. lblGettingStarted:

Getting started
===============

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: from
Linux or MacOSX,

.. parsed-literal::

   javac -cp ../../lib/|ampl_jar_raw| FirstExample.java
   java -cp ../../lib/|ampl_jar_raw|:. FirstExample <solver>

or from Windows,

.. parsed-literal::

   javac -cp ../../lib/|ampl_jar_raw| FirstExample.java
   java -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.

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 ``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 folder (directory) ``amplapi/lib``; binaries
needed to run any solvers that are used; and an appropriate license file for
AMPL and solvers.