.. |date| date::

===================================
Sunflower Studio Programmer's Guide
===================================
:Author: Jim Klo <jim.klo@sri.com>
:Date: |date|

.. contents:: Table of Contents


Introduction
============

Sunflower Studio is the "Integrated Development Environment" or IDE for the Sunflower software suite.
Sunflower Studio is a Java application built using the `Eclipse Rich Client Framework`_.
It is assumed the reader has some familiarity with `Eclipse plug-in development`_.


Sunflower Development Environment Configuration
===============================================

The Sunflower Developer environment is capable of bulding several Sunflower branded
products and libraries. Due to this, the development environment is designed to
be modular such that the binary output of a library project can be a dependency
for an application.  All projects make use of `Maven`_ to build, and `Artifactory`_
for storing and distributing built artifacts.  Each project is stored in its own
`Git`_ repository.

To setup a local development environment, you should use a single folder to act as
the location to *clone* each `Git`_ repository. In this example, I'm going creating
a folder named ``src-root`` inside my ``sunflower`` project folder.

.. code-block:: bash

    mkdir ~/projects/sunflower/src-root
    cd ~/projects/sunflower/src-root

From ``src-root``, clone the projects you need to develop the various Sunflower
applications and libraries. Below is a table that lists several of the projects you
may need when developing Sunflower.


    +----------------------------+---------------------+------------------------+
    |                            | Products            |                        |
    +============================+=====================+========================+
    | Module                     | Sunflower Studio CE | Sunflower Studio Tasks |
    +----------------------------+---------------------+------------------------+
    | sunflower-foundation       | X                   | X                      |
    +----------------------------+---------------------+------------------------+
    | sunflower-foundation-tasks |                     | X                      |
    +----------------------------+---------------------+------------------------+
    | sunflower-native           | X                   | X                      |
    +----------------------------+---------------------+------------------------+
    | sunflower-studio           | X                   | X                      |
    +----------------------------+---------------------+------------------------+


Source repositories can for each of the modules below can be found in the table below 

    +----------------------------+------------------------------------------------------------+
    | Name                       | URL                                                        |
    +============================+============================================================+
    | sunflower-foundation       | https://scm.sri.com/scm/git/ROR/sunflower-foundation       |
    +----------------------------+------------------------------------------------------------+
    | sunflower-foundation-tasks | https://scm.sri.com/scm/git/ROR/sunflower-foundation-tasks |
    +----------------------------+------------------------------------------------------------+
    | sunflower-native           | https://scm.sri.com/scm/git/ROR/sunflower-native           |
    +----------------------------+------------------------------------------------------------+
    | sunflower-studio           | https://scm.sri.com/scm/git/ROR/sunflower-studio           |
    +----------------------------+------------------------------------------------------------+




To extend Sunflower Studio, the developer will need to properly configure the
:doc:`development environment<developer_environment/index>`. This process involves:

1. :doc:`Install and configure Maven<developer_environment/maven>` to build the basic building blocks of Sunflower.
2. :doc:`Configuring the Eclipse PDE<developer_environment/eclipse>` for Development.
3. Installing dependencies to :doc:`build XSB and Flora<developer_environment/xsb_flora>`, so you can test your enhancements.


Sunflower Foundation
====================

Sunflower Studio integrates with Sunflower Foundation using a set of Java libraries
that are packaged within the ``com.sri.floralib`` plug-in located in the sunflower-open folder.
If you have a source license to Sunflower Foundation, this can be built and integrated
into the ``com.sri.floralib`` plug-in using Maven and the ``sunflower-bootstrap`` POM:

First you will build and install ``sunflower-foundation``:

.. code-block:: bash

    cd <source root>/sunflower-foundation
    mvn clean install

This will install locally built ``sunflower-foundation`` libraries into your local
Maven .m2 repository cache.  Next you will use the ``sunflower-bootstrap`` module to place a copy
of all the Sunflower Studio library dependencies into the ``com.sri.floralib`` bundle,
which will use your locally built ``sunflower-foundation``.

.. code-block:: bash

    cd <source root>/sunflower-studio/sunflower-bootstrap
    mvn verify -DskipTests -DbuildType=floralib-bundle

This will build Sunflower Foundation and place it libraries within ``sunflower-open/com.sri.floralib/lib2``.


Running and Debugging Sunflower Studio
======================================

Once you have fully configured your :doc:`development environment<developer_environment/index>`, you can launch Eclipse and open ``sunflower-studio-ce.product`` file within the ``com.sri.sunflower.distrib.core`` plug-in. Once you have opened the ``*.product`` file, click on the **Overview** tab, located along the bottom edge of the file view. Inside the **Testing** group, click **Synchronize** and then click either **Launch an Eclipse application** or **Launch an Eclipse application in Debug mode** to either run or debug the application, respectively.

.. figure:: figs/run_core_from_eclipse.png

   Click **Synchronize**, then click **Launch an Eclipse application** or **Launch an Eclipse application in Debug mode**.


When Sunflower Studio starts for the first time it will not be able to locate a verison of XSB or Flora to integrate with. You can either use the pre-built XSB and Flora that is included with the platform specific build, or you may use one you build yourself by following the instructions provided in the instructions to :doc:`build XSB and Flora<developer_environment/xsb_flora>`, included within the Sunflower Developer Documentation.
You can find the pre-build XSB and Flora within the ``external`` folder that contains **Sunflower Studio**.

.. figure:: figs/pre-build-xsb-flora.png

   Pre-built verions of XSB and Flora can be found in the ``external`` folder within the Sunflower Studio distribution.

Within Sunflower Studio, open the **Reasoner Preferences**, located within the **Preferences..** menu item in either the **Window** menu (Windows and Linux) or **Sunflower Studio CE** menu (Macintosh).

.. figure:: figs/sunflower-reasoner-preferences.png

   Sunflower Reasoner Preferences

Select the ``external/flora2`` folder for the **Flora-2 directory** value and ``external/XSB/config/<architecture>/bin`` where ``<architecture>`` is specific to your operating system for the **XSB binary directory** value. If you have :doc:`built your own XSB and Flora<developer_environment/xsb_flora>`, then these values should be ``<sourceroot>/floralib/flserver-build/ext/flora2`` and ``<sourceroot>/floralib/flserver-build/ext/XSB/config/<architecture>/bin`` for **Flora-2** and **XSB binary directories**, respectively. Click **Apply**, then click **OK**.  The Flora-2 reasoner should launch.

From this point forward you can import existing or create new Flora projects to work with inside your development version.


Typical Developer Workflow
==========================

For the Sunflower Studio developer, there is a typical workflow one should follow when updating from source control.

1. Update source tree:

   .. code-block:: bash

       svn up

2. Rebuild and update the dependencies for the ``sunflower-open/com.sri.floralib`` plug-in:

   .. code-block:: bash

       cd <sourceroot>/sunflower-bootstrap
       mvn clean verify -DskipTests -DbuildType=floralib-bundle

3. Within Eclipse, select :menuselection:`File --> Refresh` from the application menu.  Then select :menuselection:`Project --> Clean...`, select **Clean all projects**, then click **OK**.  This will clean out old files in the workspace that might cause conflicts.

4. If the :menuselection:`Project --> Build Automatically` menu is checked, wait for all the projects to rebuild inside Eclipse.  Otherwise select :menuselection:`Project --> Build All`. Once all errors resolve to your satisfaction [1]_, continue development within Eclipse as you desire.

.. _Git: https://git-scm.com

.. _Maven: https://maven.apache.org

.. _Artifactory: https://www.jfrog.com/artifactory/

.. _Eclipse plug-in development: https://wiki.eclipse.org/Eclipse_Plug-in_Development_FAQ

.. _Eclipse Rich Client Framework: https://wiki.eclipse.org/index.php/Rich_Client_Platform

.. [1] Some Eclipse plug-ins, such as the **E4 CSS editor** and **E4 CSS Spy** plug-ins don't fully understand Java FX CSS and incorrectly show syntax errors.