boinc/dcapi/doc/windows.xml

<?xml version="1.0"?>
<!DOCTYPE sect2 PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<sect2 id="build-windows">
  <title>On Windows</title>

  <sect3>
    <title>Prerequisites</title>

    <itemizedlist>
      <listitem>
	<para>
	  Microsoft Visual Studio 7.1
	</para>
      </listitem>
      <listitem>
	<para>
	  DC-API library and header files
	</para>
      </listitem>
      <listitem>
	<para>
	  Zip file containing the skeleton for an application
	</para>
      </listitem>
    </itemizedlist>
  </sect3>

  <sect3>
    <title>Preparing the repository</title>

    <para>
      Unzip the contents of the attached zip file. Copy the following three
      header files of the DC-API in the <filename
	class='directory'>include</filename> directory: <filename
	class='headerfile'>dc_client.h</filename>, <filename
	class='headerfile'>dc_common.h</filename>, <filename
	class='headerfile'>dc_win32.h</filename>. Copy the following library
      file of the DC-API in the <filename class='directory'>lib</filename>
      directory: <filename class='libraryfile'>dc_client.lib</filename>.
    </para>
    <para>
      The source code of the application goes into the <filename
	class='directory'>src</filename> directory, which already contains an
      application skeleton. The Visual Studio Related files are in the <filename
	class='directory'>win_build</filename> directory.
    </para>
  </sect3>

  <sect3>
    <title>Using Visual Studio to compile the application</title>

    <para>
      Open the <filename>application.sln</filename> file in Microsoft Visual
      Studio 7.1 (MVS from now on). Open up the 'Soultion Explorer' window in
      MVS, if it is not open yet
      (<keycombo><keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>L</keycap></keycombo>).
      In the 'Solution Explorer' window you will see the Solution called
      'application' to which several subdirectories belong.
    </para>
    <para>
      Open up the <filename class='directory'>Source Files</filename>
      subdirectory to check that <filename>application.c</filename> is already
      added to the solution. Double click on <filename>application.c</filename>
      to open it up in MVS. Similarily, the header files are located in the
      <filename class='directory'>Header Files</filename> subdirectory.
    </para>

    <sect4>
      <title>Adding more source files to the solution</title>

      <para>
	If you want to add more header or source files, put them in the
	<filename class='directory'>include</filename> or the <filename
	  class='directory'>src</filename> directories, respectively.  After the
	files are settled in place right click on the <filename
	  class='directory'>Source Files</filename> in the 'Solution Explorer'
	and choose
	<menuchoice>
	  <guimenu>Add</guimenu>
	  <guimenuitem>Add Existing Item</guimenuitem>
	</menuchoice>
	from the menu to add the source files. Do the same for the header files
	to add them to the <filename class='directory'>Header Files</filename>
	directory.
      </para>
    </sect4>

    <sect4>
      <title>Developing the application</title>

      <para>
	The source file <filename>application.c</filename> already contains the
	neccessary include files and some basic functions for an application
	utilizing the DC-API to compile. The source is structured in an
	intuitive way. You can use these functions to realize the several
	functions of a BOINC application (like checkpointing) or you can clear
	these and develop your own methods.
      </para>
    </sect4>

    <sect4>
      <title>Compiling the solution</title>

      <para>
	The skeleton 'application' solution is set up to compile with the
	DC-API. In the middle part on the menu of MVS there is a drop down box
	showing <guimenuitem>Debug</guimenuitem> or
	<guimenuitem>Release</guimenuitem>. With this drop down box, you can
	select different configurations to compile your application with. Before
	compiling set this to the appropriate configuration.
      </para>
      <para>
	If you compile in <guimenuitem>Debug</guimenuitem> mode,
	<itemizedlist>
	  <listitem>
	    <para>
	      you'll be able to debug the application by visually stepping
	      through the execution,
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      however, the executable will be bigger and will not be
	      optimalized.
	    </para>
	  </listitem>
	</itemizedlist>
	Use this mode for debugging only.
      </para>
      <para>
	If you compile in <guimenuitem>Release</guimenuitem> mode,
	<itemizedlist>
	  <listitem>
	    <para>
	      the executable will be optimalized, resulting in a faster and
	      smaller code,
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      however, you'll not be able to visually debug your applcation.
	    </para>
	  </listitem>
	</itemizedlist>
	Use this mode for compiling release versions.
      </para>
      <para>
	To compile the application select <guimenuitem>Build
	  solution</guimenuitem> from the <guimenu>Build</guimenu> menu or press
	<keycap>F7</keycap>. During compilation you will see an output window
	showing the progress of the compilation.
      </para>
      <para>
	If compilation fails the last line of the output window will show:
	<screen>
Build: 0 succeeded, 1 failed, 0 skipped</screen>
	Scroll back in the 'Output Window' to locate the problem and correct it
	as neccessary.
      </para>
      <para>
	If compilation is successful the last line of the output window will
	show: <screen>
Build: 1 succeeded, 0 failed, 0 skipped
	</screen>
      </para>
      <para>
	During compilation a subdirectory is created in the <filename
	  class='directory'>win_build</filename>
	directory of the repository having the same name as the current
	configuration (Debug or Release) You will find the compiled executable
	in these subdirectories with the name
	<application>application_1.00_windows_intelx86.exe</application>.
      </para>

    </sect4>
    <sect4>
      <title>Debugging the application</title>

      <para>
	If the application is successfully compiled in
	<guimenuitem>Debug</guimenuitem> mode, you can debug it visually. During
	debugging the current directory where the application will look for its
	input and output files will the <filename
	  class='directory'>win_build</filename> directory. Copy the input files
	of the application in the <filename
	  class='directory'>win_build</filename> directory. Select
	<guimenuitem>Step Into</guimenuitem> from the <guimenu>Debug</guimenu>
	menu to start debugging or press <keycap>F11</keycap>. If the
	application is outdated, MVS will ask to recompile it, select
	<guimenuitem>Yes</guimenuitem>. The applcation will be started and you
	will see a yellow arrow pointing to the current line of code to be
	executed. Keep pressing <keycap>F11</keycap> to step through the program
	lines. If the next call is a function, you can skip the function
	by pressing <keycap>F10</keycap> (<guimenuitem>Step Over</guimenuitem>)
	and continue debugging on the point where the function returns.
      </para>

      <para>
	You can set breakpoints in the code by clicking on the grey area next to
	the program line, where the yellow arrow moves during debugging. A big
	red dot appears marking a breakpoint.
      </para>
      <para>
	To clear the breakpoint click on the big red dot or select
	<guimenuitem>Clear All Breakpoints</guimenuitem>
	(<keycombo><keycap>Ctrl</keycap><keycap>Shift</keycap><keycap>F9</keycap></keycombo>)
	from the 'Debug' menu. You can start the application in debug mode by
	selecting <guimenuitem>Start</guimenuitem> from the
	<guimenu>Debug</guimenu> menu, or by pressing <keycap>F5</keycap>.
	Execution will be breaken on the point where you have set breakpoints.
	To continue execution after a breakpoint press <keycap>F5</keycap>.
      </para>
      <para>
	To stop debugging press
	<keycombo><keycap>Shift</keycap><keycap>F5</keycap></keycombo> or select
	the <guimenuitem>Stop Debugging</guimenuitem> item in the menu of MVS.
      </para>
    </sect4>
    <sect4>
      <title>Changing configuration properties</title>

      <para>
	You can change the properties of 'Debug' and 'Release' modes by right
	clicking on the 'applcation' in the 'Solution Explorer' window and
	selecting <guimenuitem>Properties</guimenuitem>. However, the
	configuration is already set up to best suit the needs of application
	development with DC-API so in most cases no configuration option is
	needed to be changed.
      </para>
    </sect4>
  </sect3>
</sect2>
<!-- vim: set ai sw=2 tw=80: -->