.. |date| date:: .. _build_with_maven: ********************************* How To Build Sunflower with Maven ********************************* :Author: Jim Klo :Date: |date| .. contents:: Table of Contents Prerequisites ============= 1. Apache Maven http://maven.apache.org/ 2. Java SDK 1.8 http://www.oracle.com/technetwork/java/javase/downloads/index.html update your ``~/.mavenrc`` set the ``JAVA_HOME`` environment variable to the Java SDK 1.8 location if Java 1.8 is NOT your default JAVA SDK. Configure Maven with Artifactory ================================ There are two ways use maven with Artifactory. If you are only using Artifactory with Sunflower, you may wish to configure Maven globally. You may use :download:`this maven-settings.xml ` as a sample or merge with an existing maven settings file located at ``~/.m2/settings.xml``. If you use Maven with other repositories and wish to avoid conflicts, instead of copying the ``maven-settings.xml`` into your ``.m2`` folder, use ``-s src-root/build/maven-settings.xml`` as an additional argument to maven. .. note:: Further instructions in this document will assume a globally configured Maven using ``~/.m2/settings.xml``. .. _artifactory-credentials: Artifactory Credentials ----------------------- You should use your own user credentials when using the SRI Artifactory server within Maven. To configure this login to `Artifactory `_ .. figure:: ./figs/Artifactory_Login.png :width: 512 :alt: Artifactory Login Page Artifactory Login Page Once logged into Artifactory, click on your username in the upper right corner to visit the *User Profile* page. .. figure:: ./figs/Artifactory_Welcome.png :width: 512 :alt: Click on your username in the upper right. Click on your username in the upper right. From the *User Profile* page, enter your password into the *Current Password* field and click *Unlock*. .. figure:: ./figs/Artifactory_UserProfile.png :width: 512 :alt: Enter your password into the *Current Password* field and click *Unlock* Enter your password into the *Current Password* field and click *Unlock* This should now have unlocked your *Encrypted Password*. Scroll to the bottom of the page, and you will see a section titled *Authentication Settings*. Click the clipboard icon to the right of the *Encrypted Password* field to copy the password for pasting into your Maven ``settings.xml`` file. .. figure:: ./figs/Artifactory_EncryptedPassword.png :width: 512 :alt: Click the clipboard icon to the right of the Encrypted Password field to copy the password for your Maven ``settings.xml`` Select the segment of XML and copy this into your Maven ``settings.xml`` Add the following ``server`` element into the ``servers`` element your ``settings.xml`` if it does not exist. Update the ``username`` element from ``[your username]`` to your Artifactory username and the ``password`` element from ``[your encrypted password]`` to you Artifactory encrypted password that you copied from above. .. code-block:: xml :linenos: :emphasize-lines: 2-6 sunflower [your username] [your encrypted password] Quickstart Builds ================= In order to build all packages required from source for Sunflower Studio without any prior requisite artifacts ever being installed you must run each of the following Quickstart Builds in the order presented. 1. Sunflower Foundation 2. Sunflower Studio For all builds, start out by creating a root source directory for all of your Sunflower development (modify this step for your platform). .. code-block:: bash mkdir /Users/username/sunflower/source cd /Users/username/sunflower/source .. note:: Throughout the rest of this guide, we will refer to this root source directory as ``src-root`` within instructions and code snippets. .. _quickstart-sf-foundation: Quickstart Build: Sunflower Foundation ====================================== 1. Check out the source for Sunflower Foundation substituting your LDAP login for ``USERNAME`` .. code-block:: bash git clone https://USERNAME@scm.sri.com/scm/git/ROR/sunflower-foundation sunflower-foundation 2. Go to the sunflower-foundation folder and build and install modules into your local ``.m2`` cache. .. code-block:: bash cd /src-root/sunflower-foundation mvn clean install .. note:: If the ``mvn`` command fails due to a JUnit test failing, you may add the following option, ``-DskipTests`` to disable the execution of unit tests during the build. Example for above step: .. code-block:: bash mvn clean install -DskipTests Quickstart Build: Sunflower Studio ================================== 1. Check out the source for Sunflower Studio substituting your LDAP login for ``USERNAME`` .. code-block:: bash cd /src-root git clone https://USERNAME@scm.sri.com/scm/git/ROR/sunflower-studio sunflower-studio 2. Go to the bootstrap module and build Sunflower Studio .. code-block:: bash cd /src-root/sunflower-studio/sunflower-bootstrap 3. There are two varieties of Sunflower Studio, CE and Tasks. For source licenses that can build CE, use the following .. code-block:: bash mvn verify -DbuildType=core For source licenses that can build Tasks, use the following .. code-block:: bash mvn verify -DBuildType=tasks .. warning:: This step retrieves many dependencies from the Internet. Depending upon your network connectivity and computer speed, this step can take approximately 30 minutes to an hour to complete the first time. .. note:: If the ``mvn`` command fails due to a JUnit test failing, you may add the following option, ``-DskipTests`` to disable the execution of unit tests during the build. Example for above steps: .. code-block:: bash mvn verify -DbuildType=core -DskipTests mvn verify -DbuildType=tasks -DskipTests Built artifacts will be located: +------------------------+---------------------------------------------------------------------------------------------+ | Sub Project | Artifact Path | +========================+=============================================================================================+ | Sunflower Studio Tasks | ``src-root/sunflower-studio/sunflower-sri/com.sri.sunflower.distrib.tasks/target/products`` | +------------------------+---------------------------------------------------------------------------------------------+ | Sunflower Studio CE | ``src-root/sunflower-studio/sunflower-open/com.sri.sunflower.distrib.core/target/products`` | +------------------------+---------------------------------------------------------------------------------------------+ | Floralib | ``src-root/sunflower-foundation/floralib/target`` | +------------------------+---------------------------------------------------------------------------------------------+ | Floralib External | ``src-root/sunflower-foundation/floralib-ext/target`` | +------------------------+---------------------------------------------------------------------------------------------+ Maven Notes =========== Artifacts within the following locations should *NOT* be ``mvn install``'ed: .. code-block:: bash src-root/sunflower-studio Artifacts within the following locations *SHOULD* be mvn install'ed: .. code-block:: bash src-root/sunflower-foundation More Advanced Builds ==================== The following scenarios assume you have already checked out the source. Make Only Sunflower Foundation Tasks ------------------------------------ The following will only bulid the sunflower-tasks.jar file in the target directory and then install them into the .m2 repository. This is used by Sunflower Studio Tasks edition, and is only needed if building and developing the Tasks edition. If you are editing Sunflower Foundation Tasks and Sunflower Studio Tasks, this module should be built **after** Sunflower Foundation and **before** Sunflower Studio. 1. Check out the source for Sunflower Foundations Tasks from GIT .. code-block:: bash cd src-root git clone https://USERNAME@scm.sri.com/scm/git/ROR/sunflower-foundation-tasks sunflower-foundation-tasks 2. Build and install the module. .. code-block:: bash cd src-root/sunflower-foundation-tasks/sunflower-tasks mvn -DskipTests install Make The Floralib Eclipse bundle -------------------------------- When debugging the the Sunflower IDE (either core or tasks version), you will need an updated Floralib Eclipse bundle built before you can launch Sunflower from the debugger. .. code-block:: bash cd src-root/sunflower-studio/sunflower-bootstrap mvn verify -DbuildType=floralib-bundle .. note:: If this does *NOT* work, add "clean" before "verify". .. code-block:: bash mvn clean verify -DbuildType=floralib-bundle If this does not work due to a unit test failure. Add ``-DskipTests`` at the end. .. code-block:: bash mvn clean verify -DbuildType=floralib-bundle -DskipTests Make the Floralib and Tasks Eclipse bundles ------------------------------------------- When debugging the the Sunflower IDE (tasks version), you will need an updated Floralib and Tasks Eclipse bundle built before you can launch Sunflower from the debugger. .. code-block:: bash cd src-root/sunflower-studio/sunflower-bootstrap mvn verify -DbuildType=tasks-bundle .. note:: If this does *NOT* work, add "clean" before "verify". .. code-block:: bash mvn clean verify -DbuildType=tasks-bundle If this does not work due to a unit test failure. Add ``-DskipTests`` at the end. .. code-block:: bash mvn clean verify -DbuildType=tasks-bundle -DskipTests Make Sunflower Core and Floralib -------------------------------- This would be a typical core build of the Sunflower IDE assuming that JRE and XSB/Flora artifacts have been previously installed. .. code-block:: bash cd src-root/sunflower-studio/sunflower-bootstrap mvn verify -DbuildType=core .. note:: If this does *NOT* work, add "clean" before "verify". .. code-block:: bash mvn clean verify -DbuildType=core If this does not work due to a unit test failure. Add ``-DskipTests`` at the end. .. code-block:: bash mvn clean verify -DbuildType=core -DskipTests Building Without SRI Artifactory Access ======================================= It is possible to build Sunflower without access to the Maven repository. To do this you must first build and install the dependencies into your local .m2 repository. floralib-thalamus ----------------- This contains dependencies that are used by floralib-ext. These are pre-built unmanaged artifacts, that only need to be installed. To install to your local .m2, .. code-block:: bash cd src-root/sunflower-foundation/floralib-thalamus mvn install XSB and Flora ------------- You can build the XSB and Flora dependencies if you have Vagrant and Virtualbox available on an OS X host. You will need access to the SRI intranet to access the Vagrant box images the first time. Currently there is no solution for non-OS X hosts. 1. Clone the Sunflower Native repository from GIT .. code-block:: bash cd src-root git clone https://USERNAME@scm.sri.com/scm/git/ROR/sunflower-native sunflower-native 2. Change directory to the ``build`` directory .. code-block:: bash cd src-root/sunflower-native/build 3. Execute the builder script, this will take a VERY long time: .. code-block:: bash ../sunflower-native-build/jenkins-build-all-platforms-cpp.sh "" ../sunflower-native 4. Install the artifacts: .. code-block:: bash cd sunflower-native-build/floralib.artifacts mvn install .. note:: There is a way to build only a single native platform, however currently there is no method to package artifacts for a single platform. There are 3 versions, ``osx``, ``linux``, ``windows``. To do this the structure of the command is: .. code:: bash cd src-root/sunflower-native/build ../sunflower-native-build/jenkins-build-all-platforms-cpp.sh Where the values for .. code-block:: bnf :- osx | linux | windows :- "Relative path to src-root/sunflower-foundation-native/sunflower-native" For OS X: .. code:: bash cd src-root/sunflower-native/build ../sunflower-native-build/jenkins-build-all-platforms-cpp.sh osx ../sunflower-native For Linux: .. code:: bash cd src-root/sunflower-native/build ../sunflower-native-build/jenkins-build-all-platforms-cpp.sh linux ../sunflower-native For Windows: .. code:: bash cd src-root/sunflower-native/build ../sunflower-native-build/jenkins-build-all-platforms-cpp.sh windows ../sunflower-native