Finalising your first program
Now that we have created our first master piece, we should learn how to store, document and package the product for future reference.

First Steps
If you created your C++ project within the SVN working directory you can continue to the next steps, however if not you can copy your project from its current directory to "C:\svn_working_folder\Projects\Trunk".

Doxygen Code Comments
It is good practice to place helpful comments throughout your code, to maximise this further a free application called Doxygen has been created by Dimitri van Heesch to compile your code and comments into a HTML document (and other formats). I'm not going to give a full tutorial on this application as this can be viewed at http://www.stack.nl/~dimitri/doxygen/manual.html, however I will show you this in practice using the Hello World! example.

Doxygen  uses a slightly different variation of the standard comment tags ("/*!" Start Multi-line comments, "///" Single line comments)  and also allows built in Doxygen functions ("\brief", "\param", etc) to provide enhanced formatting within the output. This is all documented on the Doxygen website.  The following code of the Hello World! Example has been updated to use the new comment tags and functions, the captialised 'DECLARATION, DEFINITION & COMMENT' tags have been added by me to further enchance the output...

Hello World! C++ Code with Doxygen friendly comments and functions 


/*! 
 \file main.cpp
 \brief My First Steps : C++ Game Development - Hello World! Example

 A simple hello world C++ program to demonstrate the SDL library and test the environment.

 \author Matt Wakeling
 \date 17th May 2010
*/

#include <cstdio>
#include <sdl.h>

/// DECLARATION : Declare SurfaceDetails Function.
void SDL_SurfaceDetails(char * strName, SDL_Surface *objSurface);

/*! 
 \brief DEFINITION : Define main function, allows arguments to be passed.

 DESCRIPTION : C++ Main code entry point, no arguements have been passed to the function.
 
 \param argc - Set the number of arguements passed to the function.
 \param argv[] - Array of arguements passed to the function.
 \return int - Returns an integer value to show completion status (0 = Successful).
*/
int main(int argc, char* argv[])
{
 /// COMMENT : Start Function.

 /// COMMENT : Initialise SDL Library and Video Subsystem.
 if (SDL_Init(SDL_INIT_VIDEO) < 0) {
  fprintf(stderr, "Unable to initialise SDL Library: %s\n", SDL_GetError());
  exit(1);
    }
 
 /// COMMENT : Set Window Title.
 SDL_WM_SetCaption("Hello World!", "Hello World");

 /// COMMENT : Define SDL_Surface object to represent program window.
 SDL_Surface* objScreen = SDL_SetVideoMode(624, 117, 0, 0);
 SDL_SurfaceDetails("Screen Object", objScreen);
 
 /// COMMENT : Define SDL_Surface object for the HelloWorld! Bitmap.
 SDL_Surface* objHelloWorld_Bitmap = NULL;
 try
    {
  objHelloWorld_Bitmap = SDL_LoadBMP("HelloWorld.bmp");
  if( objHelloWorld_Bitmap == NULL )
   throw SDL_GetError() ;

  SDL_SurfaceDetails("HelloWorld! Bitmap", objHelloWorld_Bitmap);
 }
 catch( char* strError )
    {
  printf("Error Loading Bitmap : %d \n",strError);
  return -1;
    }
 

 /// COMMENT : Define SDL_Surface object to represent program buffer.
 SDL_Surface* objBuffer = SDL_DisplayFormat(objHelloWorld_Bitmap);
 SDL_SurfaceDetails("Buffer Object", objBuffer);

 /// COMMENT : Free Allocated Memory for HelloWorld! Bitmap (as it has now no longer required).
 SDL_FreeSurface(objHelloWorld_Bitmap);

 SDL_Event objSDLEvent;
 bool bolQuit = false;

 /// COMMENT : Main Program Loop.
 while(!bolQuit)
 {
  /// COMMENT : Check the message queue for an event
  if (SDL_PollEvent(&objSDLEvent))
  {
   /// COMMENT : Check if Program Window has been closed.
   if (objSDLEvent.type == SDL_QUIT)
   {
    bolQuit = true;
   }
   
   /// COMMENT : Check if [ESC] Key has been pressed.
   if (objSDLEvent.type == SDL_KEYDOWN && objSDLEvent.key.keysym.sym == SDLK_ESCAPE)
   {
    bolQuit = true;
   }
  }

  /// COMMENT : Blit the buffer object to the main screen.
  SDL_BlitSurface(objBuffer, NULL, objScreen, NULL);

  /// COMMENT : Update the entire main screen.
  SDL_UpdateRect(objScreen, 0, 0, 0, 0);
 }

 /// COMMENT : Free Allocated Memory for Buffer object (as it has now no longer required).
 SDL_FreeSurface(objBuffer);

 /// COMMENT : Quit and perform cleanup of SDL.
 SDL_Quit();

 /// COMMENT : Exit Program and Return no errors code (0 = Successful).
 return 0;

 /// COMMENT : End Function.
}


/*! 
 \brief DEFINITION : Define Surface Details Function for reference.

 DESCRIPTION : Displays details of the SDL Surface object to the console for reference purposes.
 
 \param strName - Pointer to the user friendly name for the details to display.
 \param objSurface - Pointer to an SDL surface object.
 \return void - No information returned from function.
*/
void SDL_SurfaceDetails(char * strName, SDL_Surface *objSurface)
{
 /// COMMENT : Start Function.
 
 /// COMMENT : Display SDL surface object details to the console.
 printf("Surface Object (%s): width:%d height:%d bits_per_pixel:%d\n", strName, objSurface->w, objSurface->h, objSurface->format->BitsPerPixel);

 /// COMMENT : End Function.
}

Once your code comments have been Doxygenised, re-run the debugger to confirm you code still works as expected (comments are automatically removed in the compiled version, by the compiler).

Doxygen HTML Output
To produce the output is very simple using the Doxygen Wizard (Doxygen GUI Frontend +).
  1. In Windows Explorer create a new Doxygen working folder "C:/Doxygen/". 
  2. In Windows Explorer create a new Doxygen output folder "C:/svn_working_folder/Projects/Trunk/Project1/Doxygen_Output". 
  3. Start the DoxyWizard application (START --> Programs --> Doxygen --> DoxyWizard).
  4. Set the working directory as "C:\Doxygen".
  5. Set the project name as "HelloWorld!".
  6. Set the source code location as the project folder "C:/svn_working_folder/Projects/Trunk/Project1".
  7. Click 'Scan Recursively'.
  8. Set the destination directory within the project folder "C:/svn_working_folder/Projects/Trunk/Project1/Doxygen_Output".
  9. Click <Next>.
  10. Click 'All Entities' in the extraction mode.
  11. Click 'Optimize for C++ output' in the select programming language.
  12. Click <Next>.
  13. Click 'HTML' and 'with frames and a navigation tree' only.
  14. Click <Next>.
  15. Click 'Use built-in class diagram generator'.
  16. Select the 'RUN' tab.
  17. Click 'Run Doxygen' button.
  18. Once output is completed, click 'Show HTML Output'.
Once this is complete you should have HTML output for the project in the project folder. When you start main.html and drill-down into the information it should look similar to the following...


Release Build the C++ Project
During the development of the Hello World! Example it was far quicker selecting debug to run the application and testing any changes. Now the project is complete we need to build a release version of the code that can be deployed or distributed.
  1. Start Micorsoft Visual C++ Express 2010.
  2. Open the HelloWorld project file.
  3. In Solution Explorer right-click on the solution name and select 'Configuration Manager'.
  4. In the Configuration Manager window click the 'Configuration' drop-down button.
  5. Select 'Release'.
  6. Click <Close>.
  7. In Solution Explorer right-click on the solution name and select 'Build Solution'
The project directory will now contain a new release folder and the executable file. As this file is likely to be distributed it will also need it's dependant files (ie. HelloWorld bitmap, SDL distributed binary files).
  1. Copy "C:\svn_working_folder\Projects\Trunk\Project1\Project1\HelloWorld.bmp" to "C:\svn_working_folder\Projects\Trunk\Project1\Release".
  2. Copy SDL Distribution Binaries from install location, this is either the windows system directory or "C:\svn_working_folder\Projects\Libraries\SDL\dist" depending where you installed the libraries.

    These files are JPEG.DLL, LIBPNG13.DLL, SDL.DLL, SDL_IMAGE.DLL, SDL_MIXER.DLL, SDL_NET.DLL and ZLIB1.DLL.

    Only SDL.DLL is required for the HelloWorld! Example project.
Windows Project Installer (Inno Setup)
Now that the project has been released as an executable and all dependant files have been copied to the directory,  Inno Setup will combine all the files into one setup installation program (setup.exe).
  1. In Windows Explorer navigate to "C:\svn_working_folder\Projects\Trunk\Project1\Release".
  2. Create a text file call "Licence.txt" and populate with your licence information for the project (see General Public Licence).
  3. Create a text file call "PreInstallation.txt" and populate with your program welcome message.
  4. Create a text file call "PostInstallation.txt" and populate with your program thank you message.
  5. Start the Inno Setup Compliler application (START --> Programs --> Inno Setup 5 --> Inno Setup Compiler).
  6. In the Welcome window, select 'Create a new script file using the script wizard).
  7. Click <OK>.
  8. In the wizard welcome screen, ensure 'create a new empty script file' is not selected. 
  9. Click <Next>.
  10. Type 'HelloWorld!' in Application Name.
  11. Type 'HelloWorld! 1.0' in Application Name including Version.
  12. Type your name in Application Publisher.
  13. Type 'http://programmingexperiences.blogspot.com/' in application website.
  14. Click <Next>.
  15. Select 'Program Files Folder' for Application Destination Base Folder.
  16. Type 'HelloWorld' in Application Name.
  17. Select 'Allow user to change the application folder'.
  18. Click <Next>.
  19. In Application Main Executable File browse for you release executable (i.e. C:\svn_working_folder\Projects\Trunk\Project1\Release\HelloWorld.exe).
  20. Select 'Allow user to start the application after Setup is finished'
  21. Press 'Add File(s)' button.
  22. Add 'HelloWorld.bmp' and SDL Distribution Binaries for the release folder.
  23. Click <Open>.
  24. Click <Next>.
  25. Type 'HelloWorld' in Application Start Menu Folder Name.
  26. Select 'Allow user to change the start menu folder name'.
  27. Select 'Allow user to create a desktop icon'.
  28. Click <Next>.
  29. Browse and enter the licence file name from the release folder 'Licence.txt'.
  30. Browse and enter the pre-installation file name from the release folder 'PreInstallation.txt'.
  31. Browse and enter the post-installation file name from the release folder 'PostInstallation.txt'.
  32. Click <Next>.
  33. Select 'English'.
  34. Click <Next>.
  35. Browse and Enter the release directory location "C:\svn_working_folder\Projects\Trunk\Project1\Release" in the Compiler Output field.
  36. Type 'setup' in Base File Name field.
  37. Click <Next>.
  38. Click <Finish>.
Once Inno Setup has complete you will find a new setup.exe file in the release directory, which can be used for deployment on another PC.

GNU GENERAL PUBLIC LICENSE
A copy of the General Public Licence is you wish to use it, can be obtained from http://www.gnu.org/licenses/gpl.txt and near the bottom of the page are some tags to replace your filename, date & name.

Update SVN Repository
Once have have commented your program, compiled an executable, created the documentation and got an installation file you will want to commit all your changes back to the SVN  Repository.
  1. In Windows Explorer navigate to "C:\svn_working_folder".
  2. Right-click on  'Projects' and select 'SVNCommit'.
If you have any difficulties during the commit (for example  I had problems with the VS C++ IPCH folder) you can allways delete and re-commit using the TortoiseSVN Repo-browser.