source: trunk/Documentation/Developer/PluginHowTo/part1.tex @ 1141

Last change on this file since 1141 was 1141, checked in by Patrick Vacek, 12 years ago

HowTo guide corrections. More to come next week.

File size: 7.3 KB
Line 
1\chapter{Developer Guidelines}
2
3CrypTool 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. First of all, please follow the instructions in this document so that you do not get stuck. If you encouter a problem or error that is not described here, please let us know so we can add the appropriate information to this guide.
4
5In the following sections we will 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 can begin developing your own plugins and extensions. The basic steps are:
6\begin{itemize}
7        \item Getting all prerequisites and installing them
8        \item Accessing and downloading the source code with SVN
9        \item Compiling the source code for the first time
10\end{itemize}
11
12\section{Prerequisites}
13
14Since CrypTool 2.0 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 to other platforms.) We have successfully tested with \textbf{Windows XP} and \textbf{Windows Vista}.
15
16Since you are reading the developer guidlines, you probably want to develop something. Hence, you will need a development environment. In order to compile our sources you need \textbf{Microsoft Visual Studio 2008 Professional}. Please always install the latest service packs for Visual Studio. Unfortunately, our sources do 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. However, the C\# Express version cannot handle a binary as a start project, and thus debugging becomes cumbersome.
17
18Usually the installation of Visual Studio also installs the .NET framework. In order to run or compile our source code you will need (at the time of writing) at least \textbf{Microsoft .NET 3.5 with Service Pack 1 (SP1)}. You can get this for free from Microsoft's \href{http://download.microsoft.com/download/2/0/e/20e90413-712f-438c-988e-fdaa79a8ac3d/dotnetfx35.exe}{webpage}.
19
20After the last step, your development environment should be ready for our source code. Now you will need a way of accessing and downloading the entire sources. In the CrypTool 2.0 project we use Subversion (SVN) for version control, and hence you need an \textbf{SVN client}, e.g. \textbf{TortoiseSVN} or the \textbf{svn commandline from cygwin}. It does not matter which one you use, but if you have never worked with SVN before, we suggest using \href{http://www.tortoisesvn.net/}{TortoiseSVN}, since it offers a nice Windows Explorer integration of SVN.
21
22\section{Accessing Subversion (SVN)}
23
24This section describes how to access our SVN repository and how to configure the basic settings.
25
26\subsection*{The CrypTool2 SVN URL}
27
28Our code repository is accessable at the following URL:
29
30\url{https://www.cryptool.org/svn/CrypTool2/}
31
32To access the repository, you must provide a username and password. 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).
33
34\subsection*{Accessing the SVN repository with TortoiseSVN}
35
36As already mentioned, in order to use the SVN repository one of the best options is \href{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.
37
38Later 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. If you changed a file you should choose "SVN Commit" from the context menu in order to upload your changes. Please always provide \textit{meaningfull descriptions} of your updates. You should commit your sources to our SVN repository as often as you can. This will ensure your interoperability with the rest of the project for further development.
39
40A TortoiseSVN Tutorial can be found \href{http://www.mind.ilstu.edu/research/robots/iris4/developers/svntutorial}{here}.
41
42\subsection*{Ignore patterns}
43
44In order to checkin only clean code, please use the following \textbf{ignore patterns}: \textit{"obj bin debug release *.pdb *.suo *.exe *.dll"}
45
46This 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.
47
48\section{Compiling the sources}
49
50At this point you should have checked out the entire CrypTool repository. Then compiling is pretty easy, you just go to the directory \textit{trunk/} and open the \textbf{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 \textbf{CrypWin.exe} there. When you found it, you need to right-click it and select \textbf{"Set as startup-project"} from the context menu. After you have done this, just go to the menu \textit{Build} and select \textit{Build solution} (clearly you can also use the hotkeys if you memorized them). Then go to \textit{Debug} and click \textit{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 available only as binary). In case it does not compile or start, please consult our \href{https://www.cryptool.org/trac/CrypTool2/wiki/FAQ}{F.A.Q.} and let us know if you found a bug.
51
52As a core-developer, hence somebody who can also compile CryWin and AnotherEditor, you should use the \textbf{CrypTool 2.0.sln} solution from the trunk/CoreDeveloper/ directory (this directory is \textbf{not} visible to you if you are not a core developer). As a core developer you should know, that when compiling you \textbf{change} the CryWin.exe which is visible to everybody else. Hence, when doing a checkin, please make sure you \textit{really} want to checkin a new binary.
Note: See TracBrowser for help on using the repository browser.