====== KempoMake : Adding Support ======


===== How to add support for a new OS =====

If you will be adding support for a particular platform, please talk to me first, so it's clear we have the same goals.

When adding additional platforms, please use a simple naming convention...

**Os** or **Os-HB**

**Os** Stands for Operating System, although this could be the Platform, or some other identifier if necessary.

**HB** Stands for "Home Brew", please use that if you're targeting a platform that uses only home grown based tools. This is to differentiate from official devkits.

I'm not sure which way I'll go with Acronyms... does it make more sense to go with "GameCube-HB", "GC-HB", "GCube-HB" or "Dolphin-HB"? "NES-HB" is much preferred to "NintendoEntertainmentSystem-HB", but what about "DS-HB", "DC-HB", etc? Somehow we'd need some level of obviousness for someone who say, doesn't own every system, but might be interested in building for a new one.

There also might be some differentiation of outputted binaries on some platforms depending on boot method. I hope that doesn't come up much though.

All of this said, although this system can be used for any target platform, I'm still almost solely interested in game consoles, set-top boxes, retro machines, and so on. I'm not horribly interested in 20 flavors of Linux on a PC for instance... but let's get some GCC toolchains for some obscure platforms going, and you'll have my interest.


===== Examples =====

//(**Note**: None of these are actually supported targets, you're welcome to add them though.)//

  * MacOSXPPC - PowerPC CPU, MacOSX platform, GCC?
  * PS2Linux - Mips CPU, Linux, GCC
  * PalmPilot - 68000 CPU, Palm Pilot, GCC

You'll need to make a few .mk files in your Os directory:

  * **platform-config.mk** defines the following:
    * extensions for output binaries as well as the default compiler dependancy extension(so that it can be used properly by KempoMake)
    * directories common to your platform. Go wild with this, any directory string that you need put in here.
    * a list of "common" applications. Don't go wild here, additional apps require support from within common-rules.mk which means all other platform-config.mk files will need to define the same apps as well. Currently I'm advising additional applications to go in **platform-flags-$(BUILD).mk**, though this may change.

  * **platform-rules.mk** defines custom build rules-- this is required if your toolchain isn't straight GCC, and is also good to have if your toolchain needs some custom assemblers, resource compilers, or post-build steps.

  * **platform-flags-$(BUILD).mk** - ok, here's where it gets tricky. Flags need to be organized by "Build Levels"; see the section regarding "Build Levels Explained" to see how this works. You will need to follow the Build Level rules in order to contribute to KempoMake. Replace "$(BUILD)" with "DEBUG", "PARTIAL" and "FINAL".

  * **KempoMake-$(BUILD).mk** - Defines defines, directories, and libraries all applications for a chosen platform will need to link to to build properly. This is platform specific, of course. You'll have to support the three "Build Levels" using the same rules as detailed in "Build Levels Explained." Replace "$(BUILD)" with "DEBUG", "PARTIAL" and "FINAL".

===== Build Levels Explained =====

There are three "build levels", as follows; to add a platform to the project you must respect them:
  * **DEBUG** - Generates debug symbols,    has all assertion/exception handling code, no optimizations whatsoever
  * **PARTIAL** - Generates no debug symbols, has all assertion/exception handling code, all optimizations on
  * **FINAL** - Generates no debug symbols, has no assertion/exception handling code,  all optimizations on

The idea with the build levels is simply this:
  * **DEBUG** - Internal builds, run by the programmers to find errors
  * **PARTIAL** - Internal/External builds, run by beta testers to find bugs
  * **FINAL** - External builds, this is release code, and should therefore have zero chance to assert

I will make an exception to DEBUG, however, if binaries generated are too big to actually debug with a debugger, then you may add optimizations as long as the code is still traceable.


===== Compiler/Language Setup =====

//You can use the **Linux** version of platform-rules.mk if you're basing a particular platform on a GCC toolchain. The following covers only this particular setup.//

When using C and C++, KempoMake is going to assume that we're using a GCC compatible compiler. We use this, for instance, to compile c code(we use an identical line for c++):

<code>$(CC) -c $< -o $@ -MD $(CCALLFLAGS)</code>

Where -c blah.c compiles the file "blah.c", -o blah.o outputs "blah.o"

//("-MD" is the flag that tells the compiler to make dependancies.)//

So if your target compile doesn't use -c for source file, -o for output file, and -MD for dependancy generaton, it would be best to make CC/CPLUSPLUS point to a script that can parse the command line before passing it to the compiler. This should give the best compatibility.

As far as new source languages are concerned, its pretty much open, as long as you keep the majority of the flags within platform-flags-$(BUILD).mk. Keep in mind that any "app" variables you add to platform-apps.mk should ripple out to *all* platform-apps.mk files, either as empty entries or as new entries. As well you'll need to update the comments in each file to keep everything synchronized.

All languages are assumed to be able to take a source file and turn it into an object file that can be linked into a library/application. Therefore in a list of objects in a makefile:

<code>OBJS = a.o b.o c.o d.o</code>

All of these objects could potentially refer to four different languages; a.o could refer to a.cpp, b.o could refer to b.c, c.o could refer to c.vcl, and d.o could refer to d.vsm. The make system is smart enough so that it will look for the source files within the source trees you provide for your application.

New language support should generate at the very least, one default dependancy. Currently this is what .vsm and .vcl support does, and it looks like the following:

<code>@$(ECHO) $@: $< > $*.$(DEP)</code>