% Getting the Photran Sources from Git
\vspace{-0.5in}

{\scriptsize Last modified July 22, 2013}

This describes how to check out the source code for the current \textit{development} version
of Photran.  At any given time, this is the version of Photran that will be released the
following June.

The source code you check out using this document is \textit{not} guaranteed to be stable.
There are rare points in time when it may not even compile.  So, if you have problems following
the instructions in this document, please ask for help on the ptp-dev mailing list -- 
\url{https://dev.eclipse.org/mailman/listinfo/ptp-dev}.

\textbf{Before you begin\dots}

\vspace{-1em}

\begin{enumerate}
\item Photran's source code \textit{will not compile} if you are using the wrong version of Eclipse!
      You will need to install \textit{Eclipse Classic}, also known as the \textit{Eclipse SDK},
      which includes the Eclipse Platform, Java development tools, and Plug-in Development Environment.
      (Since Photran is a set of Eclipse plug-ins, you need a distribution of Eclipse that includes the Plug-in
      Development Environment.)  What version you need depends on the time of year.
      \begin{itemize}
      \item Between January and June, you need to be running the most recent
            milestone build (in preparation for the upcoming release, which occurs in June).
            To download the latest milestone build, browse to \\
            \centerline{\url{http://download.eclipse.org/eclipse/downloads/}} \\
            and click on the link for ``4.x Stream Stable Build.''
            This will take you to a page where you can download the Eclipse SDK.
            (For example, in January--June, 2013, you will need the 4.3 Stable Stream Build
            for the upcoming Eclipse Kepler release train.)
      \item Between July and December, you can use the latest release.
            Download Eclipse Classic from \\
            \centerline{\url{http://www.eclipse.org/downloads/}}.
            (For example, in June--December, 2012, you will download Eclipse 4.2 Classic.)
      \end{itemize}
\item You will need to be running a Java 6 or later Java Virtual Machine (JVM).
\item \textit{(Optional)} You may want to install the following Eclipse plug-ins, although none of them are necessary:
      \begin{enumerate}
      \item \textbf{Subclipse} provides Subversion support -- \url{http://subclipse.tigris.org/}
      \item \textbf{FindBugs} is a static analysis/bug detection tool for Java -- \url{http://findbugs.sourceforge.net/}
      \item \textbf{EclEmma} is a tool which helps you determine the code coverage of your JUnit tests -- \url{http://www.eclemma.org/}
      \item \textbf{Metrics} provides code metrics for Java code -- \url{http://metrics.sourceforge.net/}
      \end{enumerate}
\end{enumerate}

\newcounter{running_counter}
\textbf{Part~I.  Install the CDT SDK, EGit, and Photran}  %, and Environment Descriptions}

First, you will need to install the C/C++ Development Tools Software Development Kit (CDT SDK),
EGit, and the most recent stable release of Photran itself.  Photran reuses some parts of CDT, and the
CDT SDK is required to view the source code for CDT.  EGit provides support for the Git distributed
version control system in Eclipse; it is required to access the Git repositories at the Eclipse Foundation
which contain Photran and CDT's source code.  Installing the latest release of Photran ensures that Fortran
files will be properly syntax highlighted (among other things), which is helpful when writing tests.
It is also required when setting an API baseline in Part~II below.

\begin{enumerate}
      \item Start Eclipse.  Inside Eclipse, click on the ``Help'' menu, and choose ``Install New Software...''
      \item In the ``Work with:'' combo box, choose the update site for the latest Eclipse release train.
            As of July, 2013, this should be labeled ``Kepler -- http://download.eclipse.org/releases/kepler''
      \item Expand the ``Collaboration'' category
      \item Under ``Collaboration,'' check the box next to ``Eclipse EGit''
      \item Expand the ``Programming Languages'' category
      \item Under ``Programming Languages,'' check the box next to ``C/C++ Development Tools SDK'' (Be sure the name ends with ``SDK''!)
      \item Under ``Programming Languages,'' check the box next to ``Fortran Development Tools (Photran)''
      \item Click ``Next''
      \item The wizard will show the complete list of plug-ins to be installed; click ``Next''
      \item Accept the terms of the license agreement, and click ``Finish''
      \item Installation may take several minutes. Restart Eclipse when prompted.
%      \item After Eclipse restarts, again click on the ``Help'' menu, and choose ``Install New Software...''
%      \item Click the ``Add...'' button.  In the ``Location'' field, type http://download.eclipse.org/eclipse/updates/3.8milestones
%      \item In the ``Work with:'' combo box, choose the update site you just entered, i.e.,
%            http://download.eclipse.org/eclipse/updates/3.8milestones
%      \item Expand the ``PDE/API Tools Environment Description'' category
%      \item Under ``PDE/API Tools Environment Description,'' check the boxes next to the following:
%      \begin{itemize}
%            \item PDE/API Tools Environment Descriptions J2SE 15
%            \item PDE/API Tools Environment Descriptions J2SE 16
%            \item PDE/API Tools Environment Descriptions J2SE 17
%      \end{itemize}
%      \item Click ``Next''
%      \item The wizard will show the list of environment descriptions to be installed; click ``Next''
%      \item Accept the terms of the license agreement, and click ``Finish''
%      \item Installation may take several minutes. Restart Eclipse when prompted.
	\setcounter{running_counter}{\value{enumi}}
\end{enumerate}

\vspace{1em}
\textbf{Part~II.  Set an API Baseline}

Eclipse plug-ins are required to follow very strict rules when making changes to their application
programming interface (API).  The Eclipse Plug-in Development Environment's API Tooling component enforces
these rules.  You must configure it with an API baseline so it can compare the current source code
with the latest stable release, in order to detect API changes.

\begin{enumerate}
	\setcounter{enumi}{\value{running_counter}}
	\item In Eclipse, if you are running Windows or Linux, click on the ``Window'' menu; if you are running Mac OS X, click on the ``Eclipse'' menu.
	      Choose ``Preferences'' from the menu.
	\item Expand the ``Plug-in Development'' category, and choose ``API Baselines''
	\item Click ``Add Baseline...''
	\item Enter ``Default'' for the name
	\item Click ``Reset''
	\item Click ``Finish''
	\item Click ``OK''
	\item If prompted to ``Do a full build now?'', click ``Yes''
	
	\setcounter{running_counter}{\value{enumi}}
\end{enumerate}

\vspace{1em}
\textbf{Part~III.  Clone the Photran Git repository and check out Photran's source code}

\textit{\textbf{Important:} If you already have an earlier version of the Photran source code (e.g., if you checked it out from CVS before we moved to Git),
you must \textit{delete} the existing projects from your workspace.  The Git import wizard will not overwrite them; it will give an error message and fail.}

\begin{enumerate}
	\setcounter{enumi}{\value{running_counter}}
	\item Switch to the ``Git Repository Exploring'' perspective.  (From the ``Window'' menu, choose ``Open Perspective'', and ``Other...''; choose ``Git Repository Exploring'', and click ``OK.'')
	\item From the ``File'' menu, choose ``Import...''
	\item Under ``Git'', choose ``Projects from Git'', and click ``Next''
	\item Select ``URI'', and click ``Next''
	\item In the URI field, enter one of the following.
	    \begin{itemize}
	    \item Most people will enter \\
	      \centerline{\texttt{git://git.eclipse.org/gitroot/ptp/org.eclipse.photran.git}}
	    \item If you are a committer at the Eclipse Foundation, enter \\
	      \centerline{\texttt{ssh://username@git.eclipse.org:29418/ptp/org.eclipse.photran}}
	      %\centerline{\texttt{ssh://username@git.eclipse.org/gitroot/ptp/org.eclipse.photran.git}}
	      replacing \texttt{username} with your committer username.
	    \end{itemize}
	\item Click ``Next''
	\item All branches will be selected by default; click ``Next''
	\item Make sure the local directory is OK (or change it if you want your local Git repository stored somewhere else); then click ``Next''
	\item The repository will be downloaded (it may spend several minutes ``receiving objects'').
	\item Ensure that "Import existing projects" is selected and ``Working Directory'' is selected from the list; then click ``Next''
	\item All projects are selected by default; click ``Finish''
	\item Switch back to the Java perspective.  The Package Explorer view should now contain several new projects with Photran's source code.  There should be no compilation errors (although there will be a few warnings).
	\setcounter{running_counter}{\value{enumi}}
\end{enumerate}