--------------------------------------------------------------------
 OpenXDK - Microsoft Visual Studio .NET - Installation Instructions
--------------------------------------------------------------------

 This document describes the process which should be used if you
 wish to develop "homebrew" software for the XBox using OpenXDK.

 Information is as precise and correct as I can make it, but feel
 free to submit suggestions. After all, OpenXDK is an open source
 project, and our success relies on community contributions.

------------------------------------------------------------------
 Table of Contents
------------------------------------------------------------------

 1) Installation

    a) Download
    b) Unzip
    c) Build

 2) Development

    a) Creating a New Project
    b) Removing "Debug" Configuration
    c) Setting Compiler and Linker Options
    d) Setting Required Directories
    e) Configuring CXBE for Custom Build
    f) Adding XBoxStartup
    g) Building Your Project

------------------------------------------------------------------
 Information
------------------------------------------------------------------

 1) Installation

    a) Download

    To download the latest OpenXDK files, go to the OpenXDK web site
    displayed below, and locate the appropriate download file(s).

    http://openxdk.sourceforge.net/

    Hint: You want "OpenXDK" and perhaps one of the Samples.

    b) Unzip

    OpenXDK is distributed in .zip format. After downloading OpenXDK,
    the next step is to decompress the .zip file into a directory of
    your choice. The preferred directory is C:\OpenXDK, but you may
    put these files wherever you wish. The only requirment is that
    you must remember where this directory is. 

    c) Build

    Building OpenXDK is very easy. The decompressed folder (C:\OpenXDK)
    contains a file called OpenXDK.sln. To build OpenXDK, simply open
    this workspace with Microsoft Visual Studio .NET, and then build the
    projects.

    Note: To build, click Build->Build Solution.

 2) Development

    a) Creating a New Project

    There are some specific steps that must be taken when creating a
    project for use with OpenXDK. Primarily, Compiler and Linker options
    must be tweaked, and 3 directories must be added to the compiler's
    search path. The details on how to configure these options are
    explained in detail below.

    The first step is to create a new project. This can be done by
    opening Microsoft Visual Studio .NET and creating a new Win32
    project and workspace. This can be done via File->New->Project.
    The type of project you will want to create is "Win32 Project". 
    It does not matter where you put your project files, as we will add
    the necessary directories for includes, lib, and binaries later
    in this tutorial.

    After you click OK, you will be asked what type of windows
    application you would like to create. You should click on the tab
    marked "Application Settings", and make sure "Windows Application"
    in chosen, then check the box next to "Empty Project". Then, click
    "Finish". 

    Now that you have a new project, you will need to modify a few of
    the default options before your .exe will relink correctly. The
    exact options that need to be changed are described next.

    b) Removing "Debug" Configuration

    Since you can not use "Debug" configuration with OpenXDK, it is
    recommended that you remove this configuration completely. To do
    this, use the menu Build->Configuration Manager, and in the drop
    down boxed titled "Active Solution Configuration", choose "<Edit...>"
    In the window that comes up, select "Debug", and push "Remove".
    Then click Yes on the confirmation dialog that comes up next. Once 
    this is done you can close the "Edit Solution Configurations" dialog,
    and the "Configurations Manager" dialog.

    c) Setting Compiler and Linker Options.

    Compiler options are accessed through the menu Project->Properties. 

    The first set of options we are concerned about are located under
    the "C/C++" folder. First, switch to the category titled "Code Generation"
    and set "Enable C++ Exceptions" to "no". Then, set "Buffer Security ChecK"
    to "no". Optionally, you might want to go to the category marked 
    "Optimization" and switch "Optimize for Processor" to "Pentium Pro and Above".

    The next set of options we need to change are located under the
    "Linker" folder. Switch to the category titled "Input". You will need
    to set the box marked "Ignore All Default Libraries" to "Yes". Then,
    under "Additional Dependencies", you should paste the following:

    xboxkrnl.lib xlibc.lib xhal.lib xvga.lib

    Next, you will need to add a few linker options by switching to the
    category titled "Command Line" and typing directly into the box marked
    "Additional Options". Add the following text to the very end of the
    existing text:

    /align:0x20 /driver /fixed:no

    Failure to do this correctly will result in linker errors, and you
    will not be able to compile your .xbe correctly. You can copy and
    paste the text exactly as it is above, but you must be absolutely
    certain to paste the text at the very end of the text in the box.

    After you have added these settings, just click "OK".

    d) Setting Required Directories

    In order for your code to compile and link correctly, you will need
    to add a few paths to your configuration. To add these directories,
    you can use the menu Tools->Options. Then, click over to the folder
    named "Projects". Click on the category marked "VC++ Directories" and
    add the following paths to the appropriate directory list. (You change
    between directory lists using the drop down under "Show Directories for:"

    "Include files" -> C:\OpenXDK\include\
    "Library files" -> C:\OpenXDK\lib\
    "Executable files" -> C:\OpenXDK\bin\

    You must be sure to add these directories to the correct choice under
    the drop down box titled "Show directories for:". Your paths may be
    different, depending on where you chose to unzip the OpenXDK files.

    After you have added these settings, just click "OK".

    e) Configuring CXBE for Custom Build

    Now, you must configure your project to use CXBE as a custom build step.
    This is the process that is used to convert your .exe file to an .xbe
    file that is compatible with the XBox. To configure this setting, you can
    use the menu Project->Properties, then switch to "Custom Build Step".

    Inside the box marked "Description", you can put whatever you like, but
    I usually use the following text:

    Relinking $(InputName).exe -> default.xbe

    Inside the box marked "Command Line" you will need to use the following text:

    cxbe -TITLE:"CXBX Demo" -OUT:"$(TargetDir)default.xbe" "$(TargetPath)"

    You will probably want to replace the phrase "CXBX Demo" with the title
    you want to use for your program.

    Inside the box marked "Outputs" you will need to use the following text:

    $(TargetDir)\default.xbe

    After you have added these settings, just click "OK".

    f) Adding XBoxStartup

    The last requirement to complete your project configuration is to include
    a valid entry point for your application. Typically, the below code is a
    good place to start development from:

#include <openxdk.h>

void XBoxStartup()
{
    HalReturnToFirmware(ReturnFirmwareFatal);
    return;
}

    Note: After you run the above code, your xbox will go to the "fatal" boot
    screen. It is ok, nothing is harmed, it is simply a demonstration of what
    OpenXDK can do. (Your Xbox will be back to normal after rebooting).

    g) Building Your Project

    If everything went well, you now have a valid project, and you can
    immediately start developing. Try building your project containing
    only the simple entry point as shown above, and if all goes well,
    your build will succeed and the file "default.xbe" will be created.

    You should be able to run this executable on a modded xbox.
