Overview Of Files And Folders

This section gives an overview of the important files and folders of AFC.

Conventions

Text files use

Unix line ending conventions (LF only), and
UTF-8 character encoding.

Structure

Top-Level Structure

The following folders and their subfolders are under version control:

./: License terms, build files, the documentation redirection, and project definitions (Eclipse, IDEA).
components/.../: Individual sub-components of AFC, which is each represented by its own project. See below for details.
src/: Source for documentation, build configuration, and scripts.
src/doc/: Source of the documentation in Rextile and HTML/CSS format.
lib/test/: Third-party .jar files required to test AFC components. (Test is an area, see below.)

These folders are non-versioned:

doc/: Documenation files (generated from src/doc/ by ant doc).
doc/javadoc/: Generated API documentation for AFC.
dist/: Distribution packages (generated by ant dist).
temp/: Temporary files created during builds.

Component Structure

Within each component in components/, we have the following structure. Versioned folders:

./: Build files, project definitions (Eclipse, IDEA).
./src/.../: Source files for the different areas.
./lib/.../: Third-party .jar and license files.

Non-versioned folders:

./build/: Generated .jar files (generated by ant build).
./temp/: Temporary files created during builds.

Areas

Within the src/, lib/, and temp/ folders, we often have a separation into areas. Typical areas are:

intf: Public interface
impl: Non-public implementation (but visible to other AFC components)
test: Unit tests
test-reference: Comprehensive tests (long running)
build: Code which generates other source code during build (parser definitions, for example)
patches: Custom patches to required third-party libraries as shipped in lib/

Source Types

Within the areas, the source is again split into different types of source:

java: .java source files
java-debug: .java source files for temporary debug aids which are never referenced in release builds; this path is typically enabled in the IDE, but must never be referenced in build.xml
resources: other files needed in the final .jar
data: other files not needed in the final .jar

A guiding principle is that, the intf areas should not have dependencies on anything but other intf areas. This is enforced in the build scripts.

Components

What follows is a component breakdown generated from components.yaml (there is also a more detailed breakdown including packages).

Core

AFC’s functional model to byte code compiler and runtime. The spreadsheet compiler sits on top of this and first transforms a spreadsheet into a functional model.

Runtime (formulacompiler-runtime): All the components needed to run compiled engines.
Compiler (formulacompiler-compiler): Functional model to byte code compiler. Does not have a fully sufficient public API yet. In particular, the functional model itself is not yet exposed.
Decompiler (formulacompiler-decompiler): Byte code engine decompiler.

Spreadsheet

AFC’s spreadsheet to functional model and – in the end – bytecode engine compiler.

Compiler (formulacompiler-spreadsheet): The core compiler which does everything except load and save spreadsheets in the different supported file formats.
Excel.xls (formulacompiler-spreadsheet-excel-xls): Excel .xls file format handlers.
Openoffice.ods (formulacompiler-spreadsheet-opendocument): OpenOffice .ods (OpenDocument) file format handlers.

Build Files

This gives a breakdown of the build files. There is also a detailed description of AFC’s build process and targets.

The top-level folder contains:

build.xml: Top-level Ant build script. Delegates many of its tasks to the component build scripts.
build.default.properties: Default custom build properties. You should override these in a custom build.properties file.
build.properties: Optional custom build properties. Use this to locate external tools. See build.default.properties for a list of things to define. Never put this file under version control.
components/build-common.xml: Common tasks for all of the component build scripts.
components/.../build.xml: Individual component build scripts.
src/checkstyle-config.xml: Configuration of CheckStyle for all of the Java sources in AFC. Checks the copyright header, for instance (see copyright-header.txt).
src/checkstyle-config-apionly.xml: Extended configuration of CheckStyle for all of the Java sources of AFC’s API. Enforces JavaDoc comments, for instance.
src/copyright-header.txt: Required copyright header text for all Java sources (see checkstyle-config.xml).
src/jcite-tripwires.txt: Tripwire database for JCite.

Scripts

The scripts are all Ruby scripts used to generate part of the build system and the documentation.

src/scripts/components.yaml: Component definitions with dependency information in YAML format. Input to project.rb, which in turn feeds it to the various gen-*.rb scripts.
Warning: This file must not contain hard tabs!
src/scripts/project.rb: Reads components.yaml and exposes the component structure in an accessible object model.
src/scripts/gen-macker-rules.rb: Generates temp/macker-rules.xml, which drives component dependency checking in build.xml using Macker.
src/scripts/macker-rules-template.xml: Embedded Ruby template used by gen-macker-rules.rb.
src/scripts/gen-dependency-graph.rb: Generates temp/doc/contribute/hacking/dependency-graph.dot, from which doc/contribute/hacking/dependency-graph.png is produced by dot.
src/scripts/gen-dependency-overview.rb: Generates temp/doc/contribute/hacking/packages.rextinc, which is included in the documentation.
src/scripts/gen-component-overview.rb: Generates temp/doc/contribute/hacking/components.rextinc, which is included in the documentation.

Miscellany

.project .classpath .settings/: Eclipse project definitions.
xy.iml: IDEA project definitions.
index.html: Redirection to doc/index.htm.
LICENSE.html: Top-level license terms for AFC. Duplicated in doc/LICENSE.html.