# ROSE Compiler Framework/How to add a new project directory

Most code development that is layered above the ROSE library starts out its life as a project in the projects directory. Some projects are eventually refactored into the ROSE library once they mature. This chapter describes how one adds a new project to ROSE.

### Method 1: New simple ways to add

Robb Matzke added a new feature in ROSE so you can more easily add a new project into ROSE/projects
* Create a $ROSE/projects/whatever directory.
* In that directory, create a "rose.config" file
* In that file, add the line AC_CONFIG_FILES(projects/whatever/Makefile)
rose/config/support-projects.m4 will be updated by running ./build.
You still need to have your Makefile.am. One simplest example is
* https://github.com/rose-compiler/rose-develop/blob/master/projects/SnippetTools/rose.config
* https://github.com/rose-compiler/rose-develop/blob/master/projects/SnippetTools/Makefile.am

### Method 2: Required Files

A ROSE project encapsulates a complete program or set of related programs that use the ROSE library. Each project exists as a subdirectory of the ROSE "projects" directory and should include files "README", "config/support-rose.m4", "Makefile.am", and any necessary source files, scripts, tests, etc.
* The "README" should provide an explanation about the project purpose, algorithm, design, implementation, etc.
* The "support-rose.m4" integrates the project into the ROSE build system in a manner that allows the project to be an optional component (they can be disabled, renamed, deleted, or withheld from distribution without changing any ROSE configuration files). Most older projects are lacking this file and are thus more tightly coupled with the build system.
* The "Makefile.am" serves as the input to the GNU automake system that ROSE employs to generate Makefiles.
* Each project should also include all necessary source files, documentation, and test cases.

#### Setting up support-rose.m4

The "config/support-rose.m4" file integrates the project into the ROSE configure and build system. At a minimum, it should contain a call to the autoconf AC_CONFIG_FILES macro with a list of the project's Makefiles (without the ".am" extension) and its doxygen configuration file (without the ".in" extension). It may also contain any other necessary autoconf checks that are not already performed by ROSE's main configure scripts, including code to enable/disable the project based on the availability of the project's prerequisites.
Here's an example:
Since all configuration for the project is encapsulated in the "support-rose.m4" file, renaming, disabling, or removing the project is trivial: a project can be renamed simply by renaming its directory, it can be disabled by renaming/removing "support-rose.m4", or it can be removed by removing its directory. The "build" and "configure" scripts should be rerun after any of these changes.
Since projects are self-encapsulated and optional parts of ROSE, they need not be distributed with ROSE. This enables end users to drop in their own private projects to an existing ROSE source tree without modifying any ROSE files, and it allows ROSE developers to work on projects that are not distributed publicly. Any project directory that is not part of ROSE's main Git repository will not be distributed (this includes not distributing Git submodules, although the submodule's placeholder empty directory will be distributed).

### Setting up Makefile.am

Each project should have at least one Makefile.am, each of which is processed by GNU automake and autoconf to generate a Makefile. See documentation for automake for details about what these files should contain. Some important variables and targets are:
* include $(top_srcdir)/config/Makefile.for.ROSE.includes.and.libs: This brings in the definitions from the higher level Makefiles and is required by all projects. It should be near the top of the Makefile.am.
* SUBDIRS: This variable should contain the names all the project's subdirectories that have Makefiles. It may be omitted if the project's only Makefile is in that project's top-level directory.
* INCLUDES: This would have the flags that need to be added during compilation (flags like -I$(top_srcdir)/projects/RTC/include). Your flags should be placed before $(ROSE_INCLUDES) to ensure the correct files are found. This brings in all the necessary headers from the src directory to your project.
* lib_*: These variables/targets are necessary if you are creating a library from your project, which can be linked in with other projects or the src directory later. This is the recommended way of handling projects.
* EXTRA_DIST: These are the files that are not listed as being needed to build the final object (like source and header files), but must still be in the ROSE tarball distribution. This could include README or configuration files, for example.
* check-local: This is the target that will be called from the higher level Makefiles when make check is called.
* clean-local: Provides you with a step to perform manual cleanup of your project, for instance, if you manually created some files (so Automake won't automatically clean them up).

### A basic example

Many projects start as a translator, analyzer or optimizer, which takes into input code and generate output.
A basic sample commit which adds a new project directory into ROSE: https://github.com/rose-compiler/rose/commit/edf68927596960d96bb773efa25af5e090168f4a
Please look through the diffs so you know what files to be added and changed for a new project.
Essentially, a basic project should contain
* a README file explaining what this project is about, algorithm, design, implementation, etc
* a translator acts as a driver of your project
* additional source files and headers as needed to contain the meat of your project
* test input files
* Makefile.am to
** compile and build your translator
** contain make check rule so your translator will be invoked to process your input files and generate expected results
To connect your project into ROSE's build system, you also need to
* Add one more subdir entry into projects/Makefile.am for your project directory
* Add one line into config/support-rose.m4 for EACH new Makefile (generated from each Makefile.am) used by your projects.

### Installing project targets

Install your project's content to a separate directory within the user's specified --prefix location. The reason behind this is that we don't want to pollute the core ROSE installation space. By doing so, we can reduce the complexity and confusion of the ROSE installation tree, while eliminating cross-project file collisions. It also keeps the installation tree modular.

#### Example

This example uses a prefix for installation. It also maintains Semantic Versioning.
From projects/RosePoly:

### Generate Doxygen Documentation

0. Install Doxygen tool
Using MacPorts for Apple's Mac OS:
Using one of the LLNL machines:
1. Create a Doxygen configuration file
2. Customize the configuration file (Doxyfile):
3. Generate the Doxygen documentation
4. View and verify the HTML documentation
5. Add target to your Makefile.am to generate the documentation