For general information on the Metafacture IDE see the README.
Set up and build the Metafacture IDE on the command line (requires Git, Maven 3, and Java 8):
| Clone the Git repository from GitHub: | git clone https://github.com/culturegraph/metafacture-ide.git |
| Change into ‘bundles’ of your local clone: | cd metafacture-ide/bundles |
| Run the build: | mvn clean verify |
This will run Maven to build the Metafacture IDE using the Tycho Maven plugin. A successful build will create both an Eclipse p2 repository and products with binaries for Windows, Linux, and Mac OS.
The p2 repository can be found in org.culturegraph.mf.ide.p2/target/repository (or a bundled version in org.culturegraph.mf.ide.p2/target/org.culturegraph.mf.ide.p2.zip). This p2 repository can be used to install the Metafacture IDE into an Eclipse instance (Help → Install New Software…).
The products can be found in org.culturegraph.mf.ide.p2/target/products, both bundled as zip files and unpacked in org.culturegraph.mf.ide.p2/target/products/org.culturegraph.mf.ide.p2. These products provide an Eclipse Workbench with the Metafacture IDE already installed. They can be executed by running the Metafacture-IDE executable file.
See the User Guide for instructions on using the Metafacture IDE.
To work on the Metafacture IDE in Eclipse 4.6.3 (Neon), first make sure your workbench contains the Eclipse plug-in development environment (this is already installed if you are using the Eclipse SDK i.e. _Eclipse Standard), EGit, m2e, and the Xtext SDK (these can be installed from the Neon update site: Help → Install New Software… → Work With → Neon).
To import the Metafacture IDE projects, first open the Git Repositories view in Eclipse: CTRL+3 → type ‘git’ and select the Git Repositories view. If there is no Git Repositories view, make sure EGit is installed (see above). In the view, hit Add an existing Git repository to this view, browse to the directory where you cloned the metafacture-ide Git repository, select the repository in the list, and hit Finish. Now right-click the repository in the view, choose Import Projects… and select all contained projects. After you finish the import, you should have multiple new projects in your workspace.
Now open the org.culturegraph.mf.ide/ide.target file. It should open in a forms-based editor. If it opens in a text editor, make sure the Eclipse plug-in development environment is installed (see above). In the editor, hit Set as Target Platform (in the upper right corner). This will load the required dependencies. If you have m2e (Maven integration for Eclipse) installed and you get m2e errors on the pom.xml files, open one of the files, go to a line with an error and hit Ctrl + 1 (Quick Fix). Select Discover new m2e connectors and install the suggested connectors.
This should result in a working projects setup without compiler errors. If you have issues, make sure you ran the command line build (see above) and refresh the projects (see Troubleshooting section below). To launch the Metafacture IDE, right-click the org.culturegraph.mf.ide project and select Run As → Eclipse Application.
The Flux editor of the Metafacture IDE is implemented using the Xtext language development framework. The core of this implementation is the grammar definition for the Flux language, written in Xtext’s EBNF-like grammar notation. This grammar file is located at org.culturegraph.mf.ide/src/org/culturegraph/mf/ide/Flux.xtext. The language infrastructure (the parser, editor, and other components) is generated from this file by Xtext. As part of this code generation (which happens as part of the Maven build), the source files in src-gen are overwritten. Unlike some stubs initially generated by Xtext in src, the files in src-gen are not meant to be edited manually. For further information see the comprehensive Xtext documentation.
Our development workflow is based on feature branches which are merged into the master branch using pull requests (see GitHub Flow for details and motivation). This means there is no difference in the contribution workflow for ‘core’ or ‘external’ contributors.
The first step is to fork the metafacture-ide repository on GitHub (on the Metafacture IDE GitHub page, button in the upper right corner). Then clone your fork (see Build section above), and set up your development environment. If your environment is alread set up based on the instructions above, you can simply add your GitHub fork as a new remote in your local Git repository: `git remote add [email protected]:/metafacture-ide.git` (replace <user> with your GitHub user name)
When you start working on a contribution, create a new local branch for your work: git checkout -b some-cool-feature. On that branch, commit locally until you are ready to contribute your feature or you want to open it up for discussion in a pull request.
Before you do so, make sure the build still works (see Build section above). We have set up custom compiler and Javadoc checks in Eclipse, so make sure your changes do not introduce any warnings. When you’re happy with your changes, push your local branch to your GitHub fork with git push <user> some-cool-feature, replacing <user> with the name used above to set up the remote, (or ‘origin’, if you originally cloned from your fork). Finally, open a pull request on your fork’s GitHub page (in the upper area, on the right side of the repository name).
We use Travis for continuous integration. Travis should automatically check your pull request. If there are errors (‘The Travis build failed’), and the current build status is passing (see image above in the Build section), have a look at the Travis logs (linked from the error message) to see what caused the failure. Since Travis builds in a completely clean environment, issues often involve things that are only present on your local machine (e.g. dependencies in your ~/.m2 Maven repository, local files, etc.).
When starting the Metafacture IDE via Run As → Eclipse Application fails, check its Run Configuration (Run → Run Configurations). In the Plug-ins tab, make sure ‘all workspace and enabled target components’ is selected for ‘Launch with’ (at the top).
If you have inexplicable compiler errors, try to refresh (F5) the projects and perform a clean build (Project → Clean). It’s useful to enable automatic refresh in the preferences: General → Workspace, enable ‘Refresh using native hooks or polling’ and ‘Refresh on access’.
When changing Maven dependencies, it’s sometimes necessary to update the Eclipse project config (right-click projects, Maven → Update Project…). After a Maven → Update Project… on org.culturegraph.mf.ide, select Plug-in Tools → Update Classpath to fix build issues caused by the missing classpath entry for the local jar dependency (for non-p2 dependencies, see Build section above).