Repositories

Currently, Hexatomic is developed within a single repository at https://github.com/hexatomic/hexatomic.

Push access to this repository is granted to the Hexatomic core contributors. Other contributors must work in their own fork.

Section Downloading the source code to your computer describes how to create a fork.

Project setup

Repository structure of hexatomic/hexatomic:

• Root directory
  • main POM (pom.xml)
  • .travis.yml (Configuration for the Travis continuous integration platform)
  • Meta files (.gitignore, README.md, LICENSE, CONTRIBUTING.md, CODE_OF_CONDUCT.md, etc.)
• bundles
  • bundle sub-projects
• features
  • feature sub-projects
• docs
  • source files for user and developer/maintainer documentation
• releng
  • configuration and release engineering files
• .github
  • GitHub specific configuration, such as issue templates and workflows of the GitHub Actions CI

Setup details

The Hexatomic project in the hexatomic/hexatomic repository is set up generally along the lines of Eclipse Tycho for building plug-ins, OSGi bundles and Eclipse applications - Tutorial by Lars Vogel and Simon Scholz, Version 13.03.2019, and Eclipse RCP (Rich Client Platform) - Tutorial by Lars Vogel, Version 10.12.2018.

This means that

1. It is built using Eclipse Tycho, a plugin for the Maven build system.
2. Bundles (a.k.a. "plug-ins"), i.e., units that encapsulate well-defined functionality, are located in the bundles directory.
3. Features, i.e., units that integrate one or more bundles, are located in the features directory.
4. Configuration and release engineering-related files are located in the releng directory. This includes:
   • Project configuration (for packaging, target platform configuration, etc.)
   • Product definition; in the Eclipse world, products are units that in turn integrate one or more features to define a deliverable software.
   • Target platform definition; the target platform defines the features and bundles that Hexatomic is built on top of (against).
   • Update site definition; Hexatomic's features and bundles are provided
     1. through a repository in the p2 repository format, from which Hexatomic can be updated automatically and manually from within the application in the future; and
     2. As deployable units, i.e., the actual zip files that users will download in order to get Hexatomic.
   • Miscellanea, e.g., shell scripts for deploying artifacts, templates for third-party licensing and citation, etc.
5. It uses pomless builds, i.e., not every single bundle or feature needs its own build definition XML file (pom.xml), which saves a lot of manual labour.

Project parent / root POM

Hexatomic has a root POM to build the entire project with a single Maven command, e.g., mvn clean install, issued in the root folder.

Target platform

The target platform for Hexatomic is defined using the plug-in for Eclipse. This allows to define the platform in a human-readable format, in the file org.corpus_tools.hexatomic.target.tpd. The actual target platform definition file that both the Eclipse IDE and the Tycho Maven Plugin (which is used to build Hexatomic) use is generated from this file. More details about target platforms can be found in the section Creating and activating the target platform.

Documentation

Both the user documentation and the documentation for developers and maintainers are kept in the /docs/ folder, in a subfolder for each documentation type. Documentation is written in Markdown from which websites are generated for the end user with mdbook (see section Development setup). The actual sources for the documentation can be found in the respective /src/ subfolders.

README files

All folders that are parent folders in the repository contain a README.md file that explains the contents of the folder.