Changes between Version 26 and Version 27 of DeveloperGuidlines

Apr 22, 2010, 2:20:46 PM (12 years ago)
Matthäus Wander

replaced with reference to Plugin Manual


  • DeveloperGuidlines

    v26 v27  
    1 = Developer Guidelines =
    2 [[PageOutline(2-3,Developer Guidelines)]]
    5 !CrypTool 2.0 is built upon state-of-the-art technologies such as .NET 3.5 and the Windows Presentation Foundation. Before you can start writing code and adding to the development of the project, a few things need to be considered. To make this process easier, please read through this document and follow the instructions closely. This document exists to help get you started by showing you how !CrypTool 2 plugins are built in order to succesfully interact with the application core. We have tried to be very thorough, but if you encouter a problem or error that is not described here, please let us know. Not only do we want to help get you up and running, but we also want to add the appropriate information to this guide for the benefit of other future developers.
    7 In this
    8 first chapter we will describe all steps necessary in order to compile !CrypTool 2 on your own computer. This is always the
    9 first thing you need to do before you can begin developing your own plugins and extensions. The basic steps are:
    11  * Getting all pre-requisites and installing them
    12  * Accessing and downloading the source code with SVN
    13  * Compiling the latest version of the source code
    16 == Pre-requisites ==
    18 Since !CrypTool 2 is based on Microsoft .NET 3.5, you will need a Microsoft Windows environment. (Currently no plans exist for porting this project to Mono or other platforms.) We have successfully tested with '''Windows XP''', '''Windows Vista''' and '''Windows 7'''.
    20 Since you are reading the developer guidelines, you probably want to develop something. Hence, you will need a development environment. In order to compile our sources you need '''Microsoft Visual Studio 2008 Professional'''. Make sure to always install the latest service packs for Visual Studio.
    21 Unfortunately, our sources do not work smoothly with the freely available Visual C# Express. This is due to the fact that a major part of the application core, !CrypWin, uses a commercial component and is therefore distributed only as a binary. The current version of Visual C# Express does not accept a binary file as a start-up project, and thus debugging is quite cumbersome. We hope to resolve this issue later in 2010 when the project is ported to Visual Studio 2010, but until then, we recommend using the full Visual Studio 2008 Professional version.
    23 In order to run or compile our source code you will need at least the '''Microsoft .NET 3.5 framework with Service Pack 1 (SP1)'''. Usually the installation of Visual Studio also installs the .NET framework, but if you do not have the latest version, you can get it for free from [ Microsoft's website]. Once the framework has been installed, your development environment should be ready for our source code.
    26 == Accessing the Subversion (SVN) repository ==
    27 Next you will need a way of accessing and downloading the source code. For the CrypTool 2 project we use '''Subversion (SVN)''' for version control, and hence you will need an SVN client, i.e. '''TortoiseSVN''' or the '''svn commandline from cygwin''', to access our repository. It does not matter which client you use, but if SVN is new to you, we suggest using [ TortoiseSVN], since it offers a handy, straightforward Windows Explorer integration. We will guide you through how to use TortoiseSVN, although you should be able to use any SVN client in a similar fashion.
    29 === Checking out the sources ===
    30 First, download and install TortoiseSVN. This will require you to reboot your computer, but once it is back up and running, create a directory (for instance, ''CrypTool2'') somewhere on your computer for storing the local working
    31 les. Right-click on this directory; now that TortoiseSVN has been installed, you should see a few new items in the context menu.
    33 Select ''SVN Checkout'' and a window will now appear that will ask you for the URL of the repository that you would like to access. Our code repository is stored at [], and this is what you should enter in the appropriate field. The ''Checkout directory'' should already be filled in correctly with your new folder, and you shouldn't need to change any other options.
    35 Then just hit ''OK''. You may be asked to accept a certificate (which you should accept), and you will certainly be asked for login information. If you are a registered developer, you should have already been given a username and password, and you should enter them here. (These are the same username and password that you can use for this wiki.) If you are a guest and just want to download the source code, you can use "anonymous" as the username and an empty password. Mark the checkbox for saving your credentials if you don't want to enter them every time you work with the repository. Finally, hit ''OK'', and the whole !CrypTool 2 repository will begin downloading into your chosen local directory.
    37 Since CrypTool 2 is a collaborative project with many developers, changes are made to the repository rather frequently. You should maintain a current working copy of the
    38 files to ensure your interoperability with the rest of the project, and thus you should update to the latest version as often as possible. You can do this by right-clicking on any directory within the working
    39 files and choosing ''SVN Update'' from the context menu.
    41 A TortoiseSVN tutorial can be found at [].
    43 === Adjusting the SVN settings ===
    45 If you are a registered developer, you can commit your
    46 file changes to the public !CrypTool 2 repository. However, before you do, you should edit your settings to make sure that you only check in proper source code. First, bring up the TortoiseSVN settings window. Then in the ''Global ignore pattern''
    47 field, please enter the following text:
    49 ''obj bin debug release *.pdb *.suo *.exe *.dll *.aux *.dvi *.log *.bak *.bbl *.blg *.user''
    51 You are free to also leave in any default pattern text or to write your own additions; this pattern serves simply to tell TortoiseSVN what kinds of
    52 files to ignore. You can now click ''OK'' to save your settings and close the window.
    54 === Committing your changes ===
    56 Once you start writing code and developing your plugin, you should check your work into the project repository. If you are reading this page in sequence, you are probably not ready to do this, but while we are on the topic of SVN we will describe the process. To upload your changes, right-click on a directory within the working files that contains your changes and select ''SVN Commit'' from the context menu.
    58 When you commit your code, you can leave a comment to describe what you have changed. Please always provide ''meaningful descriptions'' of your updates. You can also select exactly which
    59 files you want to check in. The ignore pattern that we recommended should prevent most undesirable
    60 files from being in the list, but double-check to make sure everything you want to upload is included but nothing more. In general, you should never check in compiled and automatically generated
    61 files. For example, do not check in the entire ''bin\'' and ''obj\'' directories that Visual Studio generates. The server will reject your commits if you try to do so. You should commit your sources to our SVN repository as often as you can, but only commit code that successfully compiles and runs!
    63 You can use the SVN comments to link to your changes to a particular issue or bug ticket in this wiki. (The list of active tickets can be found [report:1 here].) The following commands are supported (note that there are multiple variations of each command that are functionally identical):
    65  {{{
    66 closes, fixes:
    67 The specified ticket will be closed and the contents of this commit message will be added to its notes.
    69 references, refs, addresses, re:
    70 The contents of this commit message will be added to the specified ticket's notes, but the status will be left unaltered.
    71  }}}
    73 You can apply the commands to multiple tickets simultaneously. The command syntax is as follows (again note that there are multiple variations that are functionally identical):
    75  {{{
    76 command #1
    77 command #1, #2
    78 command #1 & #2
    79 command #1 and #2
    80  }}}
    82 You can also use more than one command in a message if necessary. For example, if you want to close tickets !#10 and !#12, and add a note to !#17, you could type the following:
    84  {{{
    85 Changed blah and foo to do this or that. Fixes #10 and #12, and refs #17.
    86  }}}
    88 The comments can also be used to override the ignore pattern that the server is designed to block. However, please do not do this unless you are absolutely sure that you know what you are doing. If you are, you must use the ''override-bad-extension'' command and provide an explicit list of the file and directory names that you want to upload that need to override the ignore pattern. For example, if you want to check in a library
    89 file named ''someLib.dll'', you must write something like the following:
    91  {{{
    92 This library is required by all developers, so I am adding it explicitly to the repository.
    94 override-bad-extension: someLib.dll
    95  }}}
    97 Note that any text after the colon and the whitespace will be treated as the
    98 file name. Therefore, do not use quotation marks and do not write any text after the
    99 file name.
    101 == Compiling the sources ==
    103 By this point you should have checked out a copy of the entire !CrypTool 2 repository. Compiling is pretty easy; just go to the ''trunk\'' directory and open the '''''!CrypTool 2.0.sln''''' Visual Studio solution. The Visual Studio IDE should open with all the working plugin components nicely arranged. If you are now starting Visual Studio for the first time, you will have to choose your settings. Just select either ''most common'' or ''C#'' -- you can change this at any time later. On the right side is the project explorer, where you can see all the subprojects included in the solution. Look for the project '''''!CrypWin.exe''''' there. Once you have found it, right-click on it and select ''Set as StartUp Project'' from the context menu. Next, go to the menu bar and select ''Build -> Build Solution''.
    105 You may have to wait a while for the program to compile. Once it is finished, select ''Debug -> Start Debugging''. !CrypTool 2 should now start for the
    106 first time with your own compiled code. Presumably you have not changed anything yet, but you now have your own build of all the components (with the exception of ''!CrypWin'' and ''AnotherEditor'', since they are available only as binaries). If the program does not compile or start correctly, please consult our [wiki:FAQ F.A.Q.] and let us know if you found a bug.
    108 If you are a '''core developer''', hence somebody who can also compile ''CrypWin'' and ''AnotherEditor'', you should use the '''''!CrypTool 2.0.sln''''' solution from the ''trunk\CoreDeveloper\'' directory (which will ''not'' be visible to you if you are not a core developer). As a core developer, be aware that when you compile, you '''change the ''!CrypWin.exe''''' that is visible to everybody else. Thus, when committing to the repository, please make sure you really want to check in a new binary. Core developers can also build a new setup and publish it as beta release on the website. This process is explained [BuildSetup here].
     1The '''Developer Guidelines''' have been merged with the Plugin Howto, please refer to the [source:/trunk/Documentation/Developer/PluginHowTo/HowToDeveloper.pdf Plugin Developer Manual].