Changeset 1325


Ignore:
Timestamp:
Apr 15, 2010, 5:20:01 PM (12 years ago)
Author:
Patrick Vacek
Message:

HowTo: Small improvements; moved example download section to the beginning of Chapter 2 instead of the end.

Location:
trunk/Documentation/Developer/PluginHowTo
Files:
4 edited

Legend:

Unmodified
Added
Removed
  • trunk/Documentation/Developer/PluginHowTo/HowToDeveloper.tex

    r1243 r1325  
    180180\end{itemize}
    181181
    182 This document is intended for plugin developers who want to contribute new visual or mathematical functionality to CrypTool 2. As of January 2010, the program consists of about 7000 lines of C\# code in the core application and about 250,000 lines of C\# code in 115 plugins.
     182This document is intended for plugin developers who want to contribute new visual or mathematical functionality to CrypTool 2. As of January 2010, the program consists of over 7000 lines of C\# code in the core application and over 250,000 lines of C\# code in about 100 plugins.
    183183
    184184For further information, please visit the CrypTool 2 website at  \htmladdnormallink{http://www.cryptool2.vs.uni-due.de}{http://www.cryptool2.vs.uni-due.de}.
  • trunk/Documentation/Developer/PluginHowTo/part1.tex

    r1243 r1325  
    44CrypTool 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.
    55
    6 In this first chapter we will describe all steps necessary in order to compile CrypTool 2.0 on your own computer. This is always the first thing you need to do before you can begin developing your own plugins and extensions. The basic steps are:
     6In this first chapter we will describe all steps necessary in order to compile CrypTool 2 on your own computer. This is always the first thing you need to do before you can begin developing your own plugins and extensions. The basic steps are:
    77\begin{itemize}
    88        \item Getting all prerequisites and installing them
     
    1414\label{Prerequisites}
    1515
    16 Since 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 other platforms.) We have successfully tested with \textbf{Windows XP}, \textbf{Windows Vista} and \textbf{Windows 7}.
     16Since 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 \textbf{Windows XP}, \textbf{Windows Vista} and \textbf{Windows 7}.
    1717
    1818Since 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}. Make sure to always install the latest service packs for Visual Studio. 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.
     
    2424\label{AccessingSubversion}
    2525
    26 Next you will need a way of accessing and downloading the source code. For the CrypTool 2.0 project we use Subversion (SVN) for version control, and hence you will need an \textbf{SVN client}, i.e.\ \textbf{TortoiseSVN} or the \textbf{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 \href{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.
     26Next you will need a way of accessing and downloading the source code. For the CrypTool 2 project we use \textbf{Subversion (SVN)} for version control, and hence you will need an SVN client, i.e.\ \textbf{TortoiseSVN} or the \textbf{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 \href{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.
    2727
    2828\subsection{Checking out the sources}
     
    4848\end{figure}
    4949
    50 Then just hit \textit{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 the \href{https://www.cryptool.org/trac/CrypTool2/wiki/WikiStart}{CrypTool 2 development 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 \textit{OK}, and the whole CrypTool 2 repository will begin downloading into your chosen local directory.
     50Then just hit \textit{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 the \href{https://www.cryptool.org/trac/CrypTool2/wiki/WikiStart}{CrypTool 2 development 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 \textit{OK}, and the whole CrypTool 2 repository will begin downloading into your chosen local directory.
    5151
    5252Since 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 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 files and choosing \textit{SVN~Update} from the context menu.
     
    160160\label{CompilingTheSources}
    161161
    162 By this point you should have checked out a copy of the entire CrypTool repository. Compiling is pretty easy; just go to the \textit{trunk\textbackslash } directory and open the \textbf{\textit{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 \textit{most common} or \textit{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 \textit{Set as StartUp Project} from the context menu. Next, go to the menu bar and select \textit{Build $\rightarrow$ Build Solution}.
     162By this point you should have checked out a copy of the entire CrypTool 2 repository. Compiling is pretty easy; just go to the \textit{trunk\textbackslash } directory and open the \textbf{\textit{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 \textit{most common} or \textit{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 \textit{Set as StartUp Project} from the context menu. Next, go to the menu bar and select \textit{Build $\rightarrow$ Build Solution}.
    163163
    164 You may have to wait a while for the program to compile. Once it is finished, select \textit{Debug $\rightarrow$ 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 \textit{CrypWin} and \textit{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.
     164You may have to wait a while for the program to compile. Once it is finished, select \textit{Debug $\rightarrow$ Start Debugging}. CrypTool 2 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 \textit{CrypWin} and \textit{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.
    165165
    166 If 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\textbackslash CoreDeveloper\textbackslash } 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 committing to the repository, 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}.
     166If you are a \textbf{core developer}, hence somebody who can also compile CrypWin and AnotherEditor, you should use the \textbf{\textit{CrypTool 2.0.sln}} solution from the \textit{trunk\textbackslash CoreDeveloper\textbackslash } 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{CrypWin.exe}} that is visible to everybody else. Thus, when committing to the repository, 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}.
  • trunk/Documentation/Developer/PluginHowTo/part2.tex

    r1243 r1325  
    11\chapter{Plugin Implementation}
    22\label{sec:PluginImplementation}
    3 In this chapter we provide step-by-step instructions for implementing your own CrypTool 2.0 plugin. The given instructions refer primarily to the usage of the Visual C\# Express and Visual Studio Professional 2008 editions, so before starting you should have a copy of \textbf{Microsoft Visual Studio 2008} (or \textbf{Microsoft Visual C\# 2008 Express Edition}) installed on your computer. We will use the \textbf{Caesar cipher} (also known as the \textbf{shift cipher}) as an example throughout this chapter.
     3In this chapter we provide step-by-step instructions for implementing your own CrypTool 2 plugin. The given instructions refer primarily to the usage of \textbf{Microsoft Visual Studio Professional 2008}, so before starting you should have a copy of the program installed on your computer.
     4
     5\section{Downloading the example and template}
     6\label{sec:DownloadingTheExampleAndTemplate}
     7
     8We will use the \textbf{Caesar cipher} (also known as the \textbf{shift cipher}) as an example throughout this chapter. If you did not to download the entire CrypTool 2 source code as described in Section \ref{CheckingOutTheSources}, you can still get a copy of the source code for the Caesar algorithm referenced throughout this guide from the following location:\\\\
     9\textit{username: anonymous\\
     10password:} (not required)\\
     11\url{https://www.cryptool.org/svn/CrypTool2/trunk/CrypPlugins/Caesar/}\\\\
     12We have also created a Visual Studio plugin \textbf{template} to help with the development of new plugins. Using this template is strongly recommended over copying and pasting code from this document! The template can be found here:\\\\
     13\url{http://cryptool2.vs.uni-due.de/downloads/template/encryptionplugin.zip}
    414
    515\section{Creating a new project}
     
    1424        \label{fig:vs_create_new_project}
    1525\end{figure}
    16 
    17 \noindent If you are using Visual Studio 2008, select \textbf{\textit{.NET-Framework 3.5}} as the target framework; the Express Edition will automatically choose the target framework. Then choose \textit{Class Library} as the default template, as this will build the project for your plugin as a DLL file. Give the project a unique and meaningful name (such as \textit{Caesar} in our case), and choose a location to save it to. (The Express Edition will ask for a save location later when you close your project or environment). Select the subdirectory \textit{CrypPlugins} from your SVN trunk as the location. Finally, confirm by pressing the \textit{OK} button. Note that creating a new project in this manner also creates a new solution into which the project is placed.
    18 
    19 \begin{figure}[h!]
    20         \centering
    21                 \includegraphics[width=0.80\textwidth]{figures/save_solution_csharp_express.JPG}
    22         \caption{The Visual Studio C\# Express Edition \textit{Save Project} dialog window.}
    23         \label{fig:save_solution_csharp_express}
    24 \end{figure}
    25 
    26 \noindent At this point, your Visual Studio solution should look like this:
     26\clearpage
     27
     28Select \textbf{\textit{.NET-Framework 3.5}} as the target framework. Then choose \textit{Class Library} as the default template, as this will build the project for your plugin as a DLL file. Give the project a unique and meaningful name (such as \textit{Caesar} in our case), and choose a location to save it to. Select the subdirectory \textit{CrypPlugins} from your SVN trunk as the location. Finally, confirm by pressing the \textit{OK} button. Note that creating a new project in this manner also creates a new solution into which the project is placed. At this point, your Visual Studio solution should look like this:
    2729
    2830\begin{figure}[h!]
     
    5557\clearpage
    5658
    57 Unless you have created your new project in the same CrypTool 2.0 solution, you probably will not be able to select the library directly as seen above in Figure \ref{fig:add_pluginbase_source}; instead you can browse for the binary DLL as seen below in Figure \ref{fig:browse_reference}. Click on the \textit{Browse} tab and navigate to the folder in which you downloaded the CrypTool 2 project. Within that folder, go to \textit{\textbackslash CrypPluginBase\textbackslash bin\textbackslash Debug} and select the file \textit{CrypPluginBase.dll}. The library reference can then be added by double clicking the file or pressing the \textit{OK} button.
     59Unless you have created your new project in the same CrypTool 2 solution, you probably will not be able to select the library directly as seen above in Figure \ref{fig:add_pluginbase_source}; instead you can browse for the binary DLL as seen below in Figure \ref{fig:browse_reference}. Click on the \textit{Browse} tab and navigate to the folder in which you downloaded the CrypTool 2 project. Within that folder, go to \textit{\textbackslash CrypPluginBase\textbackslash bin\textbackslash Debug} and select the file \textit{CrypPluginBase.dll}. The library reference can then be added by double clicking the file or pressing the \textit{OK} button.
    5860
    5961\begin{figure}[h!]
     
    14761478        \label{fig:sample}
    14771479\end{figure}
    1478 
    1479 \section{Downloading the example and template}
    1480 \label{sec:DownloadingTheExampleAndTemplate}
    1481 
    1482 If you chose not to download the entire CrypTool 2 source code as described in Section \ref{CheckingOutTheSources}, but you want a copy of the source code for the Caesar algorithm that was used as an example in this guide, you can download it as a Visual Studio solution from the following location:\\\\
    1483 \textit{username: anonymous\\
    1484 password:} (not required)\\
    1485 \url{https://www.cryptool.org/svn/CrypTool2/trunk/CrypPlugins/Caesar/}\\\\
    1486 We have also created a Visual Studio plugin \textbf{template} to help with the development of new plugins. This can be found here:\\\\
    1487 \url{http://cryptool2.vs.uni-due.de/downloads/template/encryptionplugin.zip}
Note: See TracChangeset for help on using the changeset viewer.