Changes between Version 24 and Version 25 of DeveloperGuidlines


Ignore:
Timestamp:
Apr 15, 2010, 10:31:58 AM (12 years ago)
Author:
Patrick Vacek
Comment:

overhaul to match HowTo guide pdf

Legend:

Unmodified
Added
Removed
Modified
  • DeveloperGuidlines

    v24 v25  
    33
    44
    5 !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.
     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 benefi
     6t of other future developers.
    67
    7 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
     8In this
     9first chapter we will describe all steps necessary in order to compile !CrypTool 2 on your own computer. This is always the
     10first thing you need to do before you can begin developing your own plugins and extensions. The basic steps are:
    811
    912 * Getting all pre-requisites and installing them
    1013 * Accessing and downloading the source code with SVN
    11  * Compiling the source-code for the first time
     14 * Compiling the latest version of the source code
    1215
    1316
    1417== Pre-requisites ==
    1518
    16 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'''. 
     19Since !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'''.
    1720
    18 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''' or '''Team System'''. Please make sure you always install the latest service packs for Visual Studio too (the current SP1 is ''not'' automatically installed by Microsoft Update). 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.
     21Since 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.
     22Unfortunately, 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 fi
     23le 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.
    1924
    20 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 [http://download.microsoft.com/download/2/0/e/20e90413-712f-438c-988e-fdaa79a8ac3d/dotnetfx35.exe webpage].
    21 
    22 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 [http://www.tortoisesvn.net TortoiseSVN], since it offers a nice windows explorer integration of SVN and any windows user should feel right away at home.
     25In 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 [http://download.microsoft.com/download/0/6/1/061F001C-8752-4600-A198-53214C69B51F/dotnetfx35setup.exe Microsoft's website]. Once the framework has been installed, your development environment should be ready for our source code.
    2326
    2427
    25 == Accessing our Subversion Control (SVN) ==
    26 This section describes how to access our SVN and the basic settings you need.
     28== Accessing the Subversion (SVN) repository ==
     29Next 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 [http://www.tortoisesvn.net/ 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.
    2730
    28 === SVN URL ===
    29 Our code repository is accessable under the following url:
     31=== Checking out the sources ===
     32First, 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
     33les. Right-click on this directory; now that TortoiseSVN has been installed, you should see a few new items in the context menu.
    3034
    31 https://www.cryptool.org/svn/CrypTool2/
     35Select ''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 [https://www.cryptool.org/svn/CrypTool2/], and this is what you should enter in the appropriate fi
     36eld. The ''Checkout directory'' should already be fi
     37lled in correctly with your new folder, and you shouldn't need to change any other options.
    3238
    33 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).
     39Then just hit ''OK''. You may be asked to accept a certi
     40cate (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.
    3441
    35 If you saved an SVN login and would like to remove it, you can either purge all authentication data in TortoiseSVN settings -> Saved data or you can locate and delete the particular saved login file in C:\Users\<User>\AppData\Roaming\Subversion\auth\svn.simple.
     42Since 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
     43files 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
     44files and choosing ''SVN Update'' from the context menu.
    3645
     46A TortoiseSVN tutorial can be found at [http://www.mind.ilstu.edu/research/robots/iris4/developers/svntutorial].
    3747
    38 === Accessing the SVN with TortoiseSVN ===
     48=== Adjusting the SVN settings ===
    3949
    40 As already mentioned, in order to use the SVN repository one of the best options is [http://www.tortoisesvn.net 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.
     50If you are a registered developer, you can commit your
     51file 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''
     52field, please enter the following text:
    4153
    42 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.
     54''obj bin debug release *.pdb *.suo *.exe *.dll *.aux *.dvi *.log *.bak *.bbl *.blg *.user''
    4355
    44 A TortoiseSVN Tutorial can be found [http://www.mind.ilstu.edu/research/robots/iris4/developers/svntutorial here].
    45 
    46 === Ignore Patterns ===
    47 
    48 In order to checkin only clean code, please use the following '''ignore patterns''':
    49 ''"obj bin debug release *.pdb *.suo *.exe *.dll *.aux *.dvi *.log *.bak *.bbl *.blg *.user"''
    50 
    51 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. Note that the server will reject your commits if you try to do so. 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. Additionally you need to explicitly provide a list of file names respectively directory names which shall override the ignore pattern. Example, you want to check in a file named ''someLib.dll'', you must write a comment which looks like this:
    52 
    53  {{{
    54 The lib is required by all developers, so I'm adding it explicitly to the repository.
    55 
    56 override-bad-extension: someLib.dll
    57 }}}
    58 
    59 Please note that any text after the colon and the whitespace will be treated as the file name. Please do not use quotes and do not write any text after the name.
     56You 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
     57files to ignore. You can now click ''OK'' to save your settings and close the window.
    6058
    6159=== Committing your changes ===
    6260
    63 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.
     61Once 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 fi
     62les that contains your changes and select ''SVN Commit'' from the context menu.
    6463
    65 You can use command words in the SVN comment to link your changes to a particular ticket.
    66 The command syntax is as follows:
     64When 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
     65files you want to check in. The ignore pattern that we recommended should prevent most undesirable
     66files 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
     67files. 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!
     68
     69You 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 [https://www.cryptool.org/trac/CrypTool2/report/1 here].) The following commands are supported (note that there are multiple variations of each command that are functionally identical):
     70
     71 {{{
     72closes, fixes:
     73The specifi
     74ed ticket will be closed and the contents of this commit message will be added to its notes.
     75
     76references, refs, addresses, re:
     77The contents of this commit message will be added to the speci
     78ed ticket's notes, but the status will be left unaltered.
     79 }}}
     80
     81You 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):
    6782
    6883 {{{
    6984command #1
    7085command #1, #2
    71 command #1 & #2 
     86command #1 & #2
    7287command #1 and #2
    7388 }}}
    7489
    75 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.
     90You 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:
    7691
    7792 {{{
    78 closes, fixes
    79   The specified issue numbers are closed with the contents of this
    80   commit message being added to it.
    81 references, refs, addresses, re
    82   The specified issue numbers are left in their current status, but
    83   the contents of this commit message are added to their notes.
     93Changed blah and foo to do this or that. Fixes #10 and #12, and refs #17.
    8494 }}}
    8595
    86 A fairly complicated example of what you can do is with a commit message of:
     96The 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
     97file named ''someLib.dll'', you must write something like the following:
     98
    8799 {{{
    88 Changed blah and foo to do this or that. Fixes #10 and #12, and refs #12.
     100This library is required by all developers, so I am adding it explicitly to the repository.
     101override-bad-extension: someLib.dll
     102 }}}
    89103
    90 This will close #10 and #12, and add a note to #12.
    91  }}}
     104Note that any text after the colon and the whitespace will be treated as the
     105file name. Therefore, do not use quotation marks and do not write any text after the
     106file name.
    92107
    93108== Compiling the sources ==
    94109
    95 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 [wiki:FAQ F.A.Q.] and let us know if you found a bug.
     110By 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 fi
     111rst 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''.
    96112
    97 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 [BuildSetup build a new setup] and publish it as beta release on the website.
     113You may have to wait a while for the program to compile. Once it is fi
     114nished, select ''Debug -> Start Debugging''. !CrypTool 2 should now start for the
     115first 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.
     116
     117If you are 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 (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 ''!CryWin.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].