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

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

HowTo: small changes and revisions over the first 18 pages

File size: 10.0 KB
Line 
1\chapter{Developer Guidelines}
2\label{DeveloperGuidelines}
3
4CrypTool 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.
5
6In 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:
7\begin{itemize}
8        \item Getting all prerequisites and installing them
9        \item Accessing and downloading the source code with SVN
10        \item Compiling the current source code for the first time
11\end{itemize}
12
13\section{Prerequisites}
14\label{Prerequisites}
15
16Since 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}, \textbf{Windows Vista} and \textbf{Windows 7}.
17
18Since 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 \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, and the current version of C\# Express cannot handle a binary as a start project, which makes debugging cumbersome. This will be resolved later in 2010 when the project is moved to Visual Studio 2010.
19
20Usually 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}. Once that has been installed, your development environment should be ready for our source code.
21
22\section{Accessing Subversion (SVN)}
23\label{AccessingSubversion}
24
25Now you will need a way of accessing and downloading the source code. 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 client 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.
26
27\subsection*{The CrypTool2 SVN URL}
28\label{TheCrypTool2SVNURL}
29
30Our code repository is accessable at the following URL:
31
32\url{https://www.cryptool.org/svn/CrypTool2/}
33
34To 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 should be the same as for the wiki).
35
36\subsection*{Accessing the repository with TortoiseSVN}
37\label{AccessingTheRepositoryWithTortoiseSVN}
38
39As mentioned above, in order to access the SVN repository one of the best options is \href{http://www.tortoisesvn.net/}{TortoiseSVN}. We will describe here how to use the basics of the program, although you should be able to use any SVN client in a similar fashion.
40
41First install TortoiseSVN (which unfortunately requires you to reboot your computer) and then create a directory (for instance ``CrypTool2") for storing the local working files somewhere on your computer. Right-click on this directory and select ``SVN Checkout" from the context menu. A window will appear in which you will be asked for the URL of the repository as given above. The ``Checkout directory" should already be filled in correctly with your new folder. Then just hit ``OK", accept the certificate (if necessary), and enter your login information as described above. Mark the checkbox for saving your credentials if you don't want to enter them every time you work with the repository. Then hit ``OK", and now the whole CrypTool2 repository should be checked out into your chosen directory.
42
43Later on, if changes have been made in the repository and you want to update your working copy, you can do this by right-clicking on any directory within the working files and choosing ``SVN Update" from the context menu. You should do this often to maintain a current version of the files.
44
45A TortoiseSVN tutorial can be found \href{http://www.mind.ilstu.edu/research/robots/iris4/developers/svntutorial}{here}.
46
47\subsection*{Committing your changes}
48\label{CommitingYourChanges}
49
50If you are a registered developer, you can commit your file changes to the public CrypTool2 repository. Right-click on the directory within the working files that contains your changes and select ``SVN Commit" from the context menu to upload your changes. Please always provide \textit{meaningful descriptions} of your updates. You should commit your sources to our SVN repository as often as you can to ensure your interoperability with the rest of the project, but only commit code that successfully compiles and runs!
51
52You can use command words in the SVN comment to link your changes to a particular ticket. The command syntax is as follows:
53
54\begin{center}
55\fbox{\parbox{15cm}
56{\tt
57command \#1\newline
58command \#1, \#2\newline
59command \#1 \& \#2\newline
60command \#1 and \#2
61}}
62\end{center}
63
64You 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.
65
66\begin{center}
67\fbox{\parbox{15cm}
68{\tt
69closes, fixes:\newline
70  The specified issue numbers are closed with the contents of this
71  commit message being added to it.
72
73references, refs, addresses, re:\newline
74  The specified issue numbers are left in their current status, but
75  the contents of this commit message are added to their notes.
76}}
77\end{center}
78
79A fairly complicated example of what you can do is with a commit message of:
80
81\begin{center}
82\fbox{\parbox{15cm}
83{\tt
84Changed blah and foo to do this or that.\ Fixes \#10 and \#12, and refs \#12.
85}}
86\end{center}
87
88This will close \#10 and \#12, and add a note to \#12.
89
90\subsection*{Ignore patterns}
91\label{IgnorePatterns}
92
93Please only check in proper source code by using the following \textbf{ignore patterns}:
94
95\begin{center}
96\textit{obj bin debug release *.pdb *.suo *.exe *.dll *.aux *.dvi *.log *.bak *.bbl *.blg *.user}
97\end{center}
98
99This basically means that you should never check in compiled and automatically generated files. For example, please do not check in the entire \textit{bin/} and \textit{obj/} directories that 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 \textit{*.dll} files by using the context menu and adding the file explicitly - but please be absolutely sure that you know what you are doing. Additionally, you need to provide an explicit list of file and directory names which should override the ignore pattern. For example, if you want to check in a file named someLib.dll, you must write a comment which looks like this:
100
101\begin{center}
102\fbox{\parbox{15cm}
103{\tt
104The lib is required by all developers, so I am adding it explicitly to the repository.
105
106override-bad-extension:\ someLib.dll
107}}
108\end{center}
109
110Please note that any text after the colon and the whitespace will be treated as the file name. Therefore, do not use quotation marks and do not write any text after the file name.
111
112\section{Compiling the sources}
113\label{CompilingTheSources}
114
115By this point you should have checked out a copy of the entire CrypTool repository. Compiling is pretty easy; just go to the \textit{trunk/} directory and open the \textbf{\textit{CrypTool 2.0.sln}} Visual Studio solution. The Visual Studio IDE should open with all the working plugins components nicely arranged. In case 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 \textbf{\textit{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" $\rightarrow$ ``Build Solution".
116
117Then go to ``Debug" and select ``Start Debugging". CrypTool 2.0 should now start for the 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 \href{https://www.cryptool.org/trac/CrypTool2/wiki/FAQ}{FAQ} and let us know if you found a bug.
118
119If you are a \textbf{core developer}, hence somebody who can also compile CryWin and AnotherEditor, you should use the \textbf{\textit{CrypTool 2.0.sln}} solution from the \textit{trunk/CoreDeveloper/} directory (which will \textit{not} be visible to you if you are not a core developer). As a core developer, be aware that when you compile, you \textbf{change the \textit{CryWin.exe}} that is visible to everybody else. Thus, when doing a check-in, please make sure you \textit{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 in the wiki at \url{https://www.cryptool.org/trac/CrypTool2/wiki/BuildSetup}.
Note: See TracBrowser for help on using the repository browser.