====================================================================== = GBAForVS6: Game Boy Advance Project AppWizard for Visual Studio 6 = = by Nick Sabalausky ("Abscissa"/"Nitrode") = ====================================================================== ================ = Description: = ================ GBAForVS6 is a Visual Studio Project AppWizard for Microsoft Visual Studio 6 that makes it easy to use Visual Studio to develop programs for Game Boy Advance. Although it is primarily an AppWizard right now, its aim is to serve as a complete Game Boy Advance development environment hosted on Visual Studio that encompasses various homebrew GBA-development tools. The goal of GBAForVS6 is to make it as easy as possible for people new to Game Boy Advance development to get started, and to streamline the development process for more experienced Game Boy Advance developers. If you currently use either of the tools "GBA Project AppWizard" (by WhatZdat D. Pimp) or VCMake, then GBAForVS6 program replaces both of them. ================= = Requirements: = ================= - Microsoft Visual Studio 6, or Microsoft Visual C++ 6: NOTE: GBAForVS6 will _NOT_ work with any version of Visual Studio .NET. However, I plan to create a version specifically for Visual Studio .NET very soon. - DevKitARM (http://www.devkit.tk): This is the compiler for GBA programs. It is required, but if you don't already have it, the "Full" distribution of GBAForVS6 can install it automatically. - A good Game Boy Advance emulator: I recommend VisualBoy Advance (http://vba.ngemu.com/). You can technically use GBAForVS6 without a GBA emulator, but it would be much more difficult to test your programs. ================= = Installation: = ================= There are two distributions of GBAForVS6: Standalone Installer: - Includes only the AppWizard and necessary helper files. DevKitARM must already be installed. Full Installer: - Includes the AppWizard and DevKitARM. Recommended for those who do not already have DevKitARM. Installation is simple. GBAForVS6 comes as an executable installer, so just download the installer, run it, and it'll do the all hard work for you. Note that if you choose to not have it install DevKitARM for you, then you'll need to tell it where to find your existing DevKitARM directory. =============== = How to use: = =============== Create a new GBA project in Visual Studio 6 by selecting "GBAForVS6 Game Boy Advance AppWizard" in the new project menu (File->New...->Projects). Give it a name, and click next. If you need to alter the paths to either DevKitARM or the main GBAForVS6 directory, then click the "Change Tool Paths" button. Otherwise, select whether you want a blank project (no source files, you add your own), a project with a blank main() as a starting point, or a small sample program. Click "Finish" and your new project will be ready to go. One of the benefits of GBAForVS6 is that it's integrated more closely to the Visual Studio interface than a normal makefile project. Specifically, you do not need to alter your makefile in order to specify which source code files in your project need to be compiled. Instead, GBAForVS6 will automatically search for files to be compiled by looking through the "Source Files" portion of the FileView panel in your Visual Studio project. So, to include or omit source files from your GBA program's build, just add or delete the source files from FileView just like you would in any other Visual Studio project. NOTE: Due to a limitation of Visual Studio 6, you will need to save your workspace via "File->Save Workspace" on the menu bar every time you add or remove source files to your project. This is because GBAForVS6 searches for source files by looking at your project file (*.dsp), and Visual Studio does NOT save the project file automatically. Note that "Save All" will NOT save your project file, you must use "Save Workspace". If you do not save your workspace when you add or remove source files then GBAForVS6 will not be able to see the changes you've made and will not be able to compile it correctly. =============================== = Known Issues / Limitations: = =============================== - You must save your workspace via "File->Save Workspace" whenever you add/remove source files from your project, otherwise GBAForVS6 won't know that you've added or removed any files ("Save All" won't work). This is due to a limitation of Visual Studio 6, and there isn't really any good workaround. The upcoming Visual Studio .NET version probably won't experience this problem. - When a header file in a GBA project is changed, GBAForVS6 does not currently know to recompile the sources that included it. This will be fixed in a future version. For now, the best workaround is to use "Rebuild All" whenever you change a header file instead of just "Build" or "Build All". - The "Execute Program" button in Visual Studio does not work on GBA projects. This is because Visual Studio doesn't understand that the output is a ROM and not a windows exe, and it doesn't know anything about running a GBA emulator. However, you *can* make it work. See the FAQ for an explanation of how to set it up. - If you try to use the Visual Studio debugger, you'll just get an error message. To my knowledge, it is not possible to use Visual Studio to debug a GBA program, and GBAForVS6 doesn't change that. To be honest, I've never really looked into using debuggers on GBA programs, so I don't know anything about what debuggers are out there, let alone how to launch one within Visual Studio. Sorry :( I may look into it sometime, though. ======== = FAQ: = ======== Q. Why did you make GBAForVS6? A. I used to use the "GBA Project AppWizard" (by WhatZdat D. Pimp) a lot, but it had stopped being updated and I got tired of its limitations and the parts that has become outdated. Specifically, it used the old DevKitAdvance instead of the newer and better DevKitARM, the makefiles it generated didn't seem to work right without some manual tweaking (which started to become an inconvenience for me), and there were some other rough edges I figured I could smooth out myself. Since the source code for it was never released (at least not to my knowledge), I couldn't update it myself. So I just made a new one to replace it. What actually motivated me to do it was a combination of wanting to have a cleaner way to create projects and being frustrated at *wanting* to answer all of the "How do I set up this GBA compiler?" posts on the GBADev.org message boards with "Just use the GBA AppWizard", but realizing that the problems with it made it just as difficult for newbies as just writing their own makefile. I also wanted a GBA Project AppWiard that would work with Visual Studio .NET, and although GBAForVS6 is still just for Visual Studio 6, I will be making a Visual Studio .NET version next. Q. Do I need to know how to use makefiles? A. No. When you create a new GBA project, the GBAForVS6 AppWizard automatically generates a working makefile for you. Q. Will the makefiles generated by GBAForVS6 work with GNU Make or (insert your favorite flavor of make here)? A. Probably not. The GBAForVS6-generated makefiles are designed specifically to work with NMAKE. This is because NMAKE comes standard with every installation of Visual Studio, and is what Visual Studio uses by default. However, I may in the future add support for Ant and/or NAnt. Q. Why don't you just have the makefile compile all of the source files in the project directory instead of having to search around the project file for them? That way, you wouldn't have to alter the makefile to add/remove files, and you wouldn't have to remember to click "File->Save Workspace" all the time. A. Two reasons. First, that would destroy the integration with Visual Studio's FileView panel. Second, it is not possible to do that with NMAKE, and I don't want GBAForVS6 to be dependent upon any flavor of make that isn't included with Visual Studio (Hence, GBAForVS6 is stuck with NMAKE which can't do it). Q. But NMAKE sucks! A. I know. :( Q. Is it possible to change the makefile template that GBAForVS6 uses when creating new projects? A. No, at least not easily. The way Visual Studio AppWizards work, all such files are included as resources in the AppWizard's DLL. It might be possible to change it if you have some sort of program that can read and modify the resources embedded in a DLL (I don't know if such a program exists). If so, the name of the DLL is (MainVisualStudioDir)\Common\MSDev98\Template\GBAForVS6.awx (Yes, that is a DLL even though the extension is "awx"). Q. Can I get the source code for GBAForVS6? A. No, or at least not yet. I plan to release the source code under the MIT License, but at the moment portions of it use sample code from Visual Studio's "Custom AppWizard" Project, and are hence copyrighted by Microsoft. The Visual Studio EULA seems a bit unclear to me on what can be done with that code (I'm not fluent in legalese), so I'm not going to release the GBAForVS6 source until I can fully replace those portions. (BTW, If anyone knows of a fully open-source or public domain skeleton AppWizard, let me know). In the meantime, I might release some source diff's if there's enough interest in it. I'll probably also release the source code for the installer (it's a script for the Nullsoft Scriptable Install System, or NSIS (http://nsis.sourceforge.net/)), but I'm going to clean it up first. It's rather messy at the moment. Q. Can I use DevKitAdvance with GBAForVS6? A. No, DevKitAdvance is long dead. If you really needed to, you could hack your project makefiles to use DevKitAdvance, but that would defeat the benefit of using GBAForVS6, and you really should be using DevKitARM instead anyway. Q. I noticed that the installer places the file "libiconv-2.dll" in one of the subdirectories of DevKitARM. Why does it do that? A. Part of the compiler (cc1.exe) requires libiconv-2.dll, but for some reason the main distribution of DevKitARM places libiconv-2.dll in a location where cc1.exe cannot find it, and so all attempts at compiling result in "DLL Not Found" errors. I'm guessing that the creators of DevKitARM probably have that dll in their windows directory or maybe set up their paths in some way that makes windows look for dlls in that dll's normal location, and hence just never noticed. I dunno . In any case, placing a copy of libiconv-2.dll in the same directory as cc1.exe fixes the problem. Q. But that's a sneaky thing to do! A. Yea, I guess it is, but the point of GBAForVS6 is to help make it easy for people to get set up writing GBA programs, and I didn't want to make anyone (especially newbies) have to deal with a big "DLL not found" error as soon as they install and try to use GBAForVS6. And I don't really want to end up having to answer a bunch of "Help, it won't work!" messages about it. Besides, unlike *truly* sneaky programs, I'm discussing it right here in this FAQ, so it's not much of a secret and any experts who don't want the extra copy of libiconv-2.dll there can still just delete it. Q. How can I make Visual Studio launch my GBA program in a GBA emulator when I click "Execute Program"? A. Go to the Debug tab in Project Settings ("Project->Settings...->Debug"). Make sure you're in the "General" category. In the "Executable for debug session:" box, enter the path and filename of your GBA emulator (Such as "C:\VBA\VisualBoyAdvance.exe"). You might need to surround it in double-quotes. Then in the box labeled "Program arguments", type in the name of your ROM file (Such as "bin\myproject.gba"). Remember to prefix it with "bin\" since GBAForVS6 places your ROM file in a subdirectory named "bin" by default. Q. Why do I have to enter settings manually to get the "Execute Program" button to work? Why can't GBAForVS6 do it automatically? A. Visual Studio 6 has some limitations on what custom AppWizards can do. It might in fact be possible to get GBAForVS6 to set that up automatically, but if it is possible I don't know how to do it at the moment. I will look into that for a future version and will do it if I can. (If you already know how to get a custom AppWizard to alter the appropriate settings in "Project Settings", let me know. It could save me a lot of MSDN-hunting ;) ) ================================== = Contact / Questions / Support: = ================================== I visit the GBADev.org Forums (http://www.gbadev.org) quite often, so if you post a message there, chances are I'll see it. Alternatively, you can reach me by email at: nick [:a t:] twistedpairgaming [:d 0 t:] com The official homepage for GBAForVS6 is at: http://www.twistedpairgaming.com/gbadev ==================== = Version History: = ==================== v1.0.1 (February 20, 2005): - Updated full distribution to include new version of DevKitARM (r11), which has been updated to gcc 3.4.3 v1.0 (December 20, 2004): - Initial Release