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.
JCrypTool mainly consists of two Git repositories, core and crypto. The core repository takes care of the JCrypTool runtime, editors, basic views, etc. The plug-ins (projects) contained in this repository are required to run the JCrypTool platform. The crypto repository contains all the algorithmns, analyses, visualizations and games for the JCrypTool platform. All plug-ins (projects) provided here are not required to run the JCrypTool platform, but they do provide the main content.
It is best to clone or fork the core and crypto repository.
JCrypTool development is based on GitFlow, and you have to familiarize yourself with these concepts before starting to develop. For an easy introduction to git, showing you all the necessary git commands, take a look at our Git Basics Tutorial. And always remember that our default development branch is develop, not master (it is impossible to push directly to master).
In case of any GitHub questions or trouble with Git or GitHub have a look at the GitHub help pages first and contact us in the JCrypTool Gitter Chat in case you do not find an answer there.
In order to develop for JCrypTool Core and/ or JCrypTool Crypto you need
- The Java Development Kit (JDK) in version 11. If you download it from adoptopenjdk.net select HotSpot as JVM type.
- Eclipse 2019-12 - download and launch the installer and select Eclipse for RCP and RAP Developers. Other packages may not be suitable for plug-in development without downloading additional features and plug-ins.
Install the Java Development Kit and Eclipse. No other plug-ins are required for your JCrypTool development. However, there are a couple of other useful plug-ins we do recommend.
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 be the 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. Otherwise you have to select Other and choose UTF-8 in the drop down box.
Click on OK to exit the preferences.
To participate in the JCrypTool Project you need to create a GitHub account. The initial GitHub setup description is available in the GitHub help section.
To clone all JCrypTool projects you have to create new repository locations for both repository URLs in the Git Repositories view. To open the view select Window in the Eclipse menu bar, then Show View and Other..., open the Git folder, select Git Repositories and click on Open. In the newly opened view click on Clone a Git repository. A wizard will then open.
On the first page of the wizard select Clone URI. Then, on the second page, enter the URIs for the repositories.
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 (depending 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....
The wizard pages lists all discovered projects. Since we need all of them click on Finish to start the import process.
That's it! All core 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 Cloning our repositories section above.
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 errors and warnings. We will fix that later.
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 of the two Discover new m2e connectors links.
This will start a wizard. Simply keep the default and click on Finish.
Follow the installation instructions and restart Eclipse. The error in org.jcryptool.products/pom.xml will be gone after that.
JCrypTool needs a set-up target platform to use several special classes. For this a version of Eclipse GEF, the Graphical Editing Framework, including Draw2d and Zest must be 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 2019-12 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.
- Open the org.jcryptool.target.target file in the org.jcryptool.target project. This will take some time since all required target plug-ins must be resolved first.
- 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, 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.
There may are some errors left. We will fix them in the next step.
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 in the eclipse menu bar and select Run Configurations....
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. Save your settings with a click on Apply. You can then start the JCT via Run. 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.