Using Visual C 2005 Express Edition

Getting Started

1. Download Visual C++ 2005 Express, available free from Microsoft.
2. Install Visual C++ 2005 Express. (if an error occurs mentioning the mscoree.dll, reinstall or install the .NET Framework 2.0)
3. Download devkitGP2X from SourceForge. The devkitPro Installer currently does not support devkitGP2X.
4. Extract devkitGP2X to c:\devkitpro, so you end up with a devkitGP2X folder inside c:\devkitpro. This is the convention recommended by devkitPro so you can have multiple devkitPro distributions in the one location.
5. Note: If you chose a development directory other than \devkitGP2X, you will need to correct the paths in "bin\arm-linux-sdl-config" and "demo\Makefile".
6. Add the bin directory to your PATH. Click on Start->Settings->Control Panel, open System->Advanced->Environment Variables, select PATH and add c:\devkitpro\devkitGP2X\bin.
7. Download sed for Win32 from [1]. Sed is used to re-format GCC warnings and errors to a format that Visual C++ can understand.
8. Extract the sed executable from the zip file and place it somewhere in the PATH. I placed it in c:\devkitpro\devkitGP2X\bin. Rename it to sed.exe.

Note: See 'Using Visual C++ 2005 Express Edition with the Microsoft Platform SDK' about setting up Express so you can create Win32 applications. For example, if you are using SDL to have the same program run on Windows and the GP2X, you will be able use the same code to build a Win32 application to test and debug your code before trying it on the GP2X where debugging is more difficult.

Note: Follow this tutorials to set up your Visual C++ 2005 to compile and link against SDL Windows programs:

1. 'Setting up Visual C++ with service pack and Platform SDK'
2. 'Setting up a SDL project in Visual C++'

Creating The Custom Build Rule

Visual C++ 2005 has a new feature called Custom Build Rules. We will use this feature to tell Visual C++ 2005 to use our arm-linux-gcc compiler instead of its built-in C/C++ compiler. To get a custom build rules file, download this zip file and extract to C:\devkitPro. This rules file replaces the Visual C++ compiler with arm-linux-gcc. arm-linux-gcc is the C compiler for Linux applications running on ARM CPUs, but it can also compile C++ source code if the source files end with a .cpp file extension.

Creating A Project

1. Create the base project
   1. Start Visual C++ 2005 Express.
   2. Create a new project (File->New->Project).
   3. Select the General category and select Empty Project.
   4. Enter a name for the project in the Name editbox.
   5. Untick the Create directory for solution checkbox.
   6. Click OK
2. Customizing the Project
   1. Open the Custom Build Rules dialog from the menu (Project->Custom Build Rules)
   2. Select the Find Existing button and locate the arm-linux.rules file you saved earlier in c:\devkitpro\devkitGP2X.
   3. Select Yes to add the path to the Rule Files Search Path.
   4. Tick the GCC Compiler checkbox.
   5. Select Ok. Visual C++ 2005 Express may show two Rule File Conflict warnings. Click Yes for both of these to allow GCC to build your C and C++ files instead of the built-in compiler.
3. Customizing to compile for your GP2X
   1. Add some source files to the project. (The GCC Compiler property page will not appear until there are some source files in the project.)
   2. Right-Click on the project name in the Solution Explorer
   3. Choose Properties from the bottom of the drop-down list.
   4. Select the General property page. In Extensions to Delete on Clean, add *.o to the end of the list.
   5. In the same menu, open the Linker category and select the General property page. Change the extension of the Output File from .exe to .gpe.
      1. You should see: $(OutDir)\$(ProjectName).exe
      2. Change to: $(OutDir)\$(ProjectName).gpe
   6. If you need to add extra include paths or want to change some of the GCC compiler options, edit these in the General property page in the GCC Compiler category.
      1. For SDL: Under "Additional Include Paths" put "C:\devkitpro\devkitGP2X\include\SDL\" if you installed to the default paths
   7. Open the GCC Linker category and select the General property page.
   8. Fill in any additional library paths and libraries needed to build your project.
   9. Select Ok on the project settings dialog.
4. Change the Linker
   1. Make sure your project is selected in the Solution Explorer (click on the project name, then...)
   2. Open the Tool Build Order dialog from the menu (Project->Tool Build Order), which will only show up if your project is selected.
   3. Move the GCC Linker entry to just after the Linker Tool entry.
   4. Select Ok
5. Make your First Build
   1. Create a new text file with the extension .link to the project. This is to trigger the arm-linux-link build rule.
   2. Build the solution (Build->Build Solution).

If you used the default Debug build configuration, the .gpe file will be in the Debug directory in your project directory.

Advanced Projects

Using the custom build rules on just one project is all well and good, but eventually you want to get into more complex applications that might be built from multiple projects. Using the arm-linux-ar custom build rule, you can create libs for use by other applications, or as part of a larger application.

The directory structure of your solution and projects becomes important when you start having multiple projects in the one solution. This is because the linker and ar rules use a wildcard to specify the input files.

Here is a suggested directory structure for a solution containing two libraries and an application.

GameSolution
  GameSolution.sln
  LibProject1
    LibProject1.vcproj
    debug
    release
    include
    source
  LibProject2
    LibProject2.vcproj
    debug
    release
    include
    source
  GameProject
    GameProject.vcproj
    debug
    release
    include
    source
  lib

Note: The debug and release folders are automatically created by Visual C++ 2005 Express.

Each project is in its own directory under the solution directory. This allows each project to have its own Debug and Release directories for the .o (object) files. So when the linker and ar use their wildcard to gather together all the .o files for a project, they will not accidentally gather the .o files for the other projects as well. It also means that the IDE can clean the object files for one project and leave the other projects intact.

Now that we have the directory structure laid out, we can start creating the projects. As opposed to the simple project instructions above, we are now going to create an empty project but with the difference being that we are going to leave the "Create directory for solution" checkbox enabled. This will start off the directory structure as shown above.

Now create two more empty projects and add them to the solution so they form the directory structure shown above.

1. Check the Custom Build Rules dialog (right-click on the project name) and make sure that the GCC Compiler rule is enabled.
2. Open the project properties for LibProject1.
3. On the General page under Configuration Properties, set the Output Directory property to $(SolutionDir)lib. This will place the .a files in the lib directory of the solution.
4. Add *.o to the Extensions to Delete on Clean property.
5. Just below that in Project Defaults, change Configuration Type to Static Library (.lib). Now you will need to hit the Apply button because this changes some of the other property pages.
6. There should now be a Librarian property page. Select this and change the Output File property to $(OutDir)\libxxxd.a where xxx is the name you wish to give your library. The d is a naming convention for debug versions of libraries (omit the d for release configurations), and naming conventions also state that the library name starts with lib and ends in .a.
7. Skip down to the GCC Compiler property page and set any properties here that you may require, such as additional include paths.
8. Click the Ok button and open the Tool Build Order dialog (right-click on the project name).
9. Select the arm-linux-ar rule and move it down next to the Librarian rule.
10. Click Ok.
11. Create a new text file in the project directory called xxx.ar (where xxx is anything you like) and add it to the project. This is simply to trigger the arm-linux-ar build rule.
12. From the Project menu, select Project Dependencies.
13. Select each project in turn in the Projects combobox and tick the projects in the Depends on list that the project is dependent on.

In our example, GameProject is dependent on LibProject1 and LibProject2, but LibProject1 and LibProject2 are not dependent on any other projects.

Now we should be ready to build the solution. Build the solution (Build->Build Solution) and if everything is good, you should end up with two .a files in the lib folder and a .gpe in the GameProject\debug folder.

Compiling for the ARM940T CPU

If you have been following the demo coding tutorials by Dzz then you will know how to create a bin file for the 940T to run. Here is how to create the 940 bin file within Visual C 2005 Express just as if you were creating a gpe.

The process requires two application passes over the compiled files, so the rules file calls a DOS batch file as the custom build rules are unable to execute more than one command for each source file. This batch file goes in the bin directory of your gp2x sdk, eg. C:\devkitPro\devkitGP2X\bin. The custom build rule expects the batch file to be called make_940_bin.bat. This batch file is in the arm-linux-rules.zip linked above in the Creating The Custom Build Rule section, so the batch file should already be in your devkitGP2X\bin directory.

As with the other custom build rules, you have to add a trigger file to the project. This one uses a file called file.940. You can put your trigger files in the SDK root folder so they can be re-used by more than one project.

Note: Is seems the entry point function for the 940 needs to be the first function to be defined in its source file and the object file containing the entry point has to be the first to be passed to the linker. Only then the ASM code for the entry point will really be at address 0 which you want. The custom build rule uses the * wildcard and thus may not always pass the correct object file as the first to the linker. Maybe the linker when passed the *.o wildcard processes the files in alphabetical order.

Note: Remember that the file objects must be passed first to the linker, and then the libraries to link with. Otherwise, it will fail under "undefined reference" errors. The arm-linux.rules provided in the link above is broken, it passes the arguments in a incorrect order. You must change the command line in the arm-940-link rule from this:

make_940_bin.bat $(TargetPath) $(TargetDir)$(TargetName).bin [AllOptions] [AdditionalOptions] $(IntDir)\*.o

To this:

make_940_bin.bat $(TargetPath) $(TargetDir)$(TargetName).bin $(IntDir)\*.o [AllOptions] [AdditionalOptions]

More Information

To avoid having to copy the .gpe and data files to the SD card in the GP2X every time you make a change, install the Samba client on the GP2X. This allows you to mount a shared directory on your PC as a directory on the GP2X. Compile your .gpe and data files into this shared directory, then use a telnet connection to the GP2X to run the application straight from the shared directory.