wiki:DeveloperGuidlines

Version 19 (modified by pretzsch, 12 years ago) (diff)

you're -> your

Developer Guidelines

CrypTool 2.0 uses state-of-the-art technologies like .NET 3.5 and WPF. In order to make your first steps towards developing something in the context of this project a few things need to be considered. In order to not get stuck, please follow the instructions on this page. If you encouter a problem/error, which is not described here, please let us know, so we can add this information to this guide.

In the following we describe all steps necessary in order to compile CrypTool 2.0 on your own. This is always the first thing you need to do before you go on developing own plugins and extensions. The basic steps are

  • Getting all pre-requisites and installing them
  • Accessing and downloading the source code with SVN
  • Compiling the source-code for the first time

Pre-requisites

Since CrypTool 2.0 is based on Microsoft .NET 3.5, you first need a Microsoft Windows environment. (Right now no plans exist for porting this project to mono and therefore other platforms.) WE successfully tested with Windows XP and Windows Vista.

Since you're reading the developer guidlines, you probably want to develop something. Hence you need a developer environment. In order to compile our sources you need Microsoft Visual Studio 2008 Professional. Please make sure you always install the latest service packs for Visual Studio too. Unfortunately it does not work (smoothly) with the freely available Visual Studio Express (C#) versions. This is due to the fact, that CrypWin uses a commercial component, and is therefore distributed only as binary. The C# Express version unfortunately cannot handle a binary as a start project, hence debuggin becomes cumbersome.

Usually the installation of Visual Studio also installs the .NET framework. In order to run/compile our source code you need (at the time of this writing) at least Microsoft .NET 3.5 with Service Pack 1 (SP1). You can get this freely from Microsofts webpage.

After the last step, your development environment should be ready for our source-code. Hence, now you need a way of accessing and downloading the entire sources. In the CrypTool 2.0 project we use SVN (subversion control) for version control, hence you need a SVN client of your choice, e.g. TortoiseSVN or the svn commandline from cygwin. If you never worked with SVN before, we suggest to download and install TortoiseSVN, since it offers a nice windows explorer integration of SVN and any windows user should feel right away at home.

Accessing our Subversion Control (SVN)

This section describes how to access our SVN and the basic settings you need.

SVN URL

Our code repository is accessable under the following url:

https://www.cryptool.org/svn/CrypTool2/

If you are a guest and just want to download our source code you can use "anonymous" as the username and an empty password. If you are a registered developer, just use your provided username and password (which is the same as for this wiki)

Accessing the SVN with TortoiseSVN

As already mentioned, in order to use the SVN repository one of the best options is TortoiseSVN. Please install TortoiseSVN (unfortunately it will ask you to reboot, which you need to do) and then create somewhere on your computer a directory (for instance "Cryptool2") for storing the local working files. Right click on this directory and select "SVN Checkout" from the context menu. In the new appearing window you must enter the URL of the repository as given above. The "Checkout directory" should be filled in correctly. After that, just hit ok, accept the certificate (if necessary) and enter your user credentials or "anonymous" for guests. Also mark the checkbox for saving your crendentials otherwise you will be asked about them for every single file. Then hit ok, and now the whole Cryptool2-repository should be checked out into the given directory.

Later on, if you just want to update (if there where changes in the repository) you can do this with right click on any directory within the working files and choose "SVN Update" from the context menu.

A TortoiseSVN Tutorial can be found here.

Ignore Patterns

In order to checkin only clean code, please use the following ignore patterns: "obj bin debug release *.pdb *.suo *.exe *.dll"

This basically means that you should never check-in compiled and user-generated files. As an example please do not check-in the entire bin/ and obj/ directories which Visual Studio generates. If you want to submit a component (binary file) despite the ignore patterns you can still add *.dll files by using the context menu and add that file explicitely - but please be absolutely sure, that you know what you are doing.

Committing your changes

If you have an SVN account (not anonymous access), you can commit your file changes to the public CrypTool2 repository. Choose "SVN Commit" from the context menu in order to upload your changes. Please always provide meaningfull descriptions of your updates.

You can use command words in the SVN comment to link your changes to a particular ticket. The command syntax is as follows:

command #1
command #1, #2
command #1 & #2 
command #1 and #2

You can have more than one command in a message. The following commands are supported. There is more than one spelling for each command, to make this as user-friendly as possible.

closes, fixes
  The specified issue numbers are closed with the contents of this
  commit message being added to it.
references, refs, addresses, re 
  The specified issue numbers are left in their current status, but 
  the contents of this commit message are added to their notes.

A fairly complicated example of what you can do is with a commit message of:

Changed blah and foo to do this or that. Fixes #10 and #12, and refs #12.

This will close #10 and #12, and add a note to #12.

Compiling the sources

At this point you should have checked out the entire CrypTool repository. Then compiling is pretty easy, you just go to the directory trunk/ and open the CrypTool 2.0.sln Visual Studio solution. Now Visual Studio should open with all working plugins and all components nicely arranged. In case you started Visual Studio now for the very first time, you must choose a certain settings - just select either "most common" or "C#" - you can change this at any time later. In the right hand you get the project explorer, where you see all the subprojects included in the solution. You have to look for the project CryWin.exe there. When you found it, you need to right-click it and select "Set as startup-project" from the context menu. After you have done this, just go to the menu Build and select Build solution (clearly you can also use the hotkeys if you memorized them). Then go to Debug and click Start debugging - now CrypTool 2.0 should start for the first time with your own compiled code - clearly you did not change yet anything, however, you have now an own build of all components (with the exception of CrypWin and AnotherEditor, since they are avaialable only as binary). In case it does not compile or start, please consult our F.A.Q. and let us know if you found a bug.

As a core-developer, hence somebody who can also compile CryWin and AnotherEditor, you should use the CrypTool 2.0.sln solution from the trunk\CoreDeveloper\ directory (this directory is not visible to you if you are not a core developer). As a core developer you should know, that when compiling you change the CryWin.exe which is visible to everybody else. Hence, when doing a checkin, please make sure you really want to checkin a new binary. As core developer you can also build a new setup and publish it as beta release on the website.