Source Code

The MorphGear source code is hosted at SourceForge under the following licenses:

Folder Layout

MorphGear consists of multiple related projects and the expected project layout is as follows: 

Common
Destiny
MorphEngine
MorphGear
MorphModules\generator
MorphModules\hugo
MorphModules\snes9x

To further clarify - Common, Destiny, MorphEngine, and MorphGear are project folders and they all share the same parent folder which can be called anything you like. MorphModules is an empty folder that also shares the same parent, but it has subfolders for each MorphModule you're building. Be certain when you check out projects from SourceForge with Subversion or TortoiseSVN that you create your working copy according to the layout above.

If you are not working on all of the projects, there is no need to check out all of them, only the ones you are working on and their dependencies. For example, MorphEngine requires Common and Destiny, but no other projects. So if you only plan to work on MorphEngine, you only need those three projects checked out to your working copy.

Project Structure

Most projects have the following folder structure:
  • bin - Top level output folder for the project. May contain subfolders for each platform such as HPC, PPC, PPC2003, and Win32.
  • doc - Any project specific documentation.
  • license - The license agreement you agree to when you make use of the source code.
  • projects - Project folders containing the IDE projects for each platform.
  • src - Contains all source code packages and files.
For Win32 you may have a projects\win32\solution folder that contains the actual solution (or workspace). Solutions can not be placed in the same folder as the project in VS .NET or when NAnt runs the build it will also build all dependent projects within the workspace. Since the NAnt scripts already know about dependencies, we don't want to duplicate effort and therefore simply put the solutions in a different folder.

Compiling Pre-requisites

Include Paths

In order to properly compile the source code, you must make some changes to the include paths within every IDE. Windows CE devices did not always come with full C runtime support and so the Common\morph project was created to fill that gap. In order for the proper header files to be included, you must do the following.

eVC++

  1. For eVC++ (both 3.0 and 4.0), select Tools and Options from the menu.
  2. Navigate to the Directories tab.
  3. Select the Pocket PC platform.
  4. Select the first CPU - Win32 (WCE SH3).
  5. Select Show directories for Include files.
  6. Add as the first (top) entry the full path to Common\morph\src\inc\PPC.
  7. Repeat the last step for every CPU of the PPC platform.
  8. Repeat this procedure for every platform, but be sure to specify the corresponding include path (HPC or PPC2003 for example). And remember to do this for every CPU in every platform!

Visual Studio .NET

  1. Select Tools and Options from the menu.
  2. Select Projects and VC++ Directories.
  3. Select Show directories for Include files.
  4. Add as the first (top) entry the full path to Common\morph\src\inc\win32.

Building

NAnt

The easiest way to build all projects and all targets is to use NAnt. Change to the Common\build folder and run the following:

nant

If you have all of your development tools configured properly, everything should go smoothly and you'll end up with all of the targets in a top level folder called Work.

Platforms

You may wish to build only a specific platform and can do so by issuing any of the following:

nant -D:win32=true
nant -D:ppc2003=true
nant -D:ppc=true
nant -D:hpc=true

Debug and Release

You can build debug only targets by adding -D:debug=true or release only targets with -D:release=true. You can also specify a different nant target such as build-debug or build-release.

Clean Up

If you need to clean up a project, issue:

nant clean

The default.build in Common\build also has a super-clean target that will wipe out everything in project bin folders and will kill the top-level Work folder.

Build Files

NAnt runs default.build first, otherwise it will run the first *.build file in the folder. You can specify a different build file with the /f:filename parameter.

Most projects will have a default.build in the root that is a copy of the Common\build\templates\project.build file. Within each platform folder under projects such as projects\PPC you will also find a platform.build (ppc.build in the last example) that corresponds to the Common\build\templates\platform.build. If you ever feel you need to update a target in a build file for a project, consider either making a separate new build file, or making the change apply to all project build files by updating the template and running the Common\build target called update-build-templates which will copy the templates out to each project folder.

These templates typically call or include platform specific build files for building projects using the Microsoft IDEs. See the *.build files in Common\build\common for more insight.

Eclipse

You can use Eclipse to check out source code, to manage the NAnt build process, and even to edit C++ source files. If you already used Subversion or TortoiseSVN to check out the projects, then you simply need to allow Eclipse to create a new workspace and then add all of the projects you checked out to this clean workspace. To add a project in Eclipse, select File then Import and pick Existing Project into Workspace. Navigate to the project folder and select it. After importing all of your projects, your workspace should look similar to the diagram below.

eclipse.jpg

By default, the projects are configured to only build the Win32 debug target. However, you can use the Make panel on the right to run the Build All target or any other custom targets you add.

Modifying Files in Projects

If you need to add a new file to a project or remove an old one that will be or was part of the build, you must update every project that references the file. For example, if we want to add test.cpp to a project, we must open eVC++ 3.0 and add the new file to the PPC and HPC projects. We must open eVC++ 4.0 to add the file to the PPC2003 project. Finally, we open Visual Studio .NET to add the file to the Win32 project. If you remove a file, you must do the same to remove it from every project.

Yes, cross-platform building is a pain. It would be possible to instead update the NAnt build scripts to call the compilers rather than the IDEs to make the projects, but that's an undertaking no one has taken up yet. Additionally, some use VS .NET as their primary IDE and want to keep the projects and solution files up to date for that purpose.

Resource Files

Do not edit resources (bitmaps, menus, strings, etc.) in Visual Studio .NET. It uses a newer resource compiler that will confuse eMbedded Visual C++. Always edit resources (*.rc) using the older compilers.