Getting started as a JCrypTool Developer

This introduction is intended for new JCrypTool developers who need to set up their Eclipse development environment and the JCrypTool workspace for the first time. In order to get you started as easy and fast as possible, please follow these instructions carefully.

Keep in mind that JCrypTool actually consists of multiple Git repositories: The core repository takes care of the JCrypTool runtime, editors, basic views, etc. The plug-ins (projects) contained in this repository are always required. The crypto repository contains different crypto plug-ins for the JCrypTool platform. All plug-ins (projects) provided here are not required to run the JCrypTool platform, but they do provide useful samples and may give you some ideas. The optional tests repository contains all test fragments and plug-ins available for the JCrypTool platform. The doc repository is another repository. This repository is not directly required for JCrypTool development, but it does contain useful resources like our Checkstyle and Java Code Formatter configurations for your development work.

Which repositories you do need to clone or fork depends on the kind of development you have in mind. Depending on your kind of development you may need your own GitHub user or you may be happy with anonymous read access.

JCrypTool development is based on GitFlow, and you have to familiarize yourself with these concepts before starting to develop. And always remember that our default development branch is develop, not master (it is impossible to push directly into master).

• In case you are a qualified member of the JCrypTool Core or Crypto team, you need to clone all repositories.
• In case you want to improve an existing core or crypto plug-in simply fork the core, crypto and test repositories and develop against this fork. Send a pull request when you are done, we will check and integrate your changes afterwards.
• In case you are developing a new crypto plug-in (e.g. in a university project) you simply clone or fork our repositories and push your new plug-in into your own and separate GitHub repository. If you want, we will integrate your new plug-in into our crypto repository when you are done.

We strongly encourage you to clone our doc repository and to set up your development environment as described below.

In case of any GitHub questions or trouble with Git or GitHub have a look at the GitHub help pages first and contact the JCrypTool Developers Group in case you do not find an answer there.

##Prerequisites In order to develop for JCrypTool Core and/ or JCrypTool Crypto you need

• A Java SE Runtime Environment (JRE) or Java SE Development Kit (JDK) version 8 or newer.
• Eclipse Neon - download the Eclipse for RCP and RAP Developers package in version 4.6.x. Other packages are not suitable for plug-in development without downloading additional features and plug-ins.
• The EGit/JGit plug-in, which should already be contained in the downloaded Eclipse package. Install it via the update manager otherwise.

Install the Java Runtime, Eclipse and, if required, the EGit plug-in. No other plug-ins are required for your JCrypTool development. However, there are a couple of other useful plug-ins we do recommend.

##Setting up your workspace When setting up Eclipse for JCrypTool development for the first time, start your Eclipse IDE with a new (empty) workspace. As JCrypTool is developed on different platforms, it is important that all platforms use a common workspace encoding; which is UTF-8. Since this may not tbe he Eclipse default you might have to change this right away once for your workspace. Open the Eclipse Preferences and select the Workspace page in the General section. Locate the Text file encoding group. In case the default is already UTF-8 you are already done. Ohterwise you have to select Other and choose UTF-8 in the drop down box.

Select the Compiler page in the Java section after that. Locate the Java compliance level drop down box and set it to 1.8.

Click on OK to exit the preferences.

###Creating a GitHub user In case you want to use a named user with or without write access you need to create an account on GitHub. The initial GitHub setup description is available in the GitHub help section.

###Cloning our repositories To clone all JCrypTool projects you have to create new repository locations for all repository URLs in the Git Repository Exploring perspective. Switch to this perspective and add the three URLs with the help of the Clone a Git repository and add the clone to this view wizard in the Git Repositories view.

The first page of the wizard requires only the URI of the Git repository. This URL depends on whether you want read or write access. Therefore open the main repository page provided by the links below and select the type of URL you need. The URLs in the following list are not directly useable as repo links!

• core: https://github.com/jcryptool/core
• crypto: https://github.com/jcryptool/crypto
• tests: https://github.com/jcryptool/tests
• doc: https://github.com/jcryptool/doc

At first, copy and paste the core URI into the URI textfield, all the other fields are extracted automatically from this information. Do not change any of the values automatically generated. Fill in your GitHub user name and your password (dependending on your GitHub security settings your password might be an application specific token). Click Next to continue to the next page.

The branches textfield will be updated with our branch information. Keep all selections and click on Next to continue.

The third page asks for the directory to store the Git repository on your computer. You can keep the suggested default or change it. Do not use your current Eclipse workspace as Git repository; always store it in a different directory. You should activate the checkbox Import all existing projects after clone finishes which imports all projects right away. Keep the other information and click on Finish.

This updates the Git Repositories view with the repository just added.

In case you have not checked the Import all existing projects after clone finishes checkbox before, you need to continue with the following import steps:

Right click on the created entry and select Import Projects....

Keep all information on the first wizard page and click on Next to continue.

The second page lists all discovered projects. Since we need all of them click on Finish to start the import process.

That's it! All projects are now available in your local workspace. In case you are interested in both JCrypTool repositories you need to clone the crypto repository as well; simply repeat all the steps described in the Checking out the sources section above. Clone the doc repository after that, but stop after the step Clone Git Repository (3) without importing projects from this repository (there aren't any).

When you are done you should check your workspace: a yellow exclamation mark in a feature project (these projects end with .feature) indicates that one or more (required) plug-ins are missing. In this case open the feature in the Feature Manifest Editor, switch to the Plug-ins tab and make sure that all listed JCrypTool plug-ins are available in your workspace.

From time to time, new projects are added to our repository. In this case you should simply repeat the import projects steps described above to import the new projects.

At this point ignore any warning in the feature projects org.jcryptool.core.dependencies.feature and org.jcryptool.core.dependencies.nl_de.feature. We will fix that later.

##Setting up Eclipse Tycho JCrypTool build is based on Eclipse Tycho, which requires Maven (M2E) and Eclipse Tycho Connector. Whereas M2E can easily be installed via the Eclipse Update Site, the Eclipse Tycho Connector requires some additional steps.

Until this is solved, you will see an error in the org.jcryptool.product/pom.xml file. To fix this, simply open this file in the Maven POM Editor and click on the error message in the title area. Click on the Discover new m2e connectors link.

This will start the Eclipse Marketplace and discover the Tycho Configurator.

Follow the installation instructions and restart Eclipse. The error will be gone after that.

##Setting up a target platform JCrypTool may already compile and run in your environment. However, we strongly recommend setting up a target platform. In case you do not want to setup a target platform you might skip this section. This however requires that a version of Eclipse GEF, the Graphical Editing Framework, including Draw2d and Zest is available in your Eclipse installation. GEF is included in the Eclipse for RCP and RAP Developers package, but might be missing in other editions. In this case use the Eclipse Neon Update Site to add GEF (and automatically its dependencies) to your environment. You do need GEF to compile and run JCrypTool. Besides that, without a target platform JCrypTool will not be fully translated since all the Eclipse translations will not be available in your environment.

1. Open the jcryptool.target file in the org.jcryptool.product project. This will take some time since all required target plug-ins must be resolved first.
2. After all plug-ins are resolved (see the progress indicator in the lower right), simply click the Set as Target Platform link in the upper right. This again will take some time.

At this point, no build errors should be left. The two features org.jcryptool.core.dependencies.feature and org.jcryptool.core.dependencies.nl_de.feature should be clear, no warnings left. Otherwise redo the first two steps from the list above. ##Starting JCrypTool in your Eclipse environment (IDE) Open the file jcryptool.product file located in the org.jcryptool.product project with the Product Configuration Editor. Simply click on the Launch an Eclipse application link in the lower left on the first page. This starts JCrypTool and creates a run menu entry.

This first run might stop with an error message. To fix this, open the run menu and select the created run menu entry (normally named jcryptool.product). Switch to the Plug-ins tab and click the Add required plug-ins button. This will add the platform dependent plug-ins to your configuration. This step is only required the first time.

JCrypTool will be launched in the language defined in your operating systems regional settings. Follow the instructions provided here to switch the active language.

Important: From time to time, new plug-ins or features will be added to the default JCrypTool configuration. After checking out those projects and/ or updating the corresponding features, you must use the Launch an Eclipse application link again to update your run entry configuration (otherwise the projects will be available in your workspace but won't be available during JCrypTool runtime). Remember to click the Add required plug-ins button after that.

Now it is time to read all about our Coding Conventions and to setup some required plug-ins.