====== LibTate Porting Guide ======
**//This document is still under revision, but should be usable.//**

===== Definitions =====

==== Common Code ====

When we talk of about "common" code, we're referring to code that is, in essence, common to all platforms. This code is the lifeblood of LibTate.

==== Peer Code ====

Certain files within LibTate contain the word "Peer" in their file names. Additionally, you'll notice in some non-peer files references to functions with the word "Peer" in them. Peer classes and code conceptually reside "inside" of the main LibTate code and are used directly from within LibTate.

Essentially peer code performs the grunt work that common code simply cannot; but at the same time, it does not perform code that can be easily abstracted into common code.

Since peer code tends to be very simple, the following observations can be made:
  * Although the grunt work is platform specific, the interface must be common to all platforms; thus we define the peer interfaces from within common code.
  * Since peer code is used from within classes themselves:
    * The peer source file is **not included** in the build step
    * The peer source file **is included** from within the non-peer file
  * Because of all of the above, peer code is **always** declared inline

[[:projects:libtate:doc:api:packages:base:alert]] and [[:projects:libtate:doc:api:packages:base:alertpeer]] are simple examples of peer code, and [[:projects:libtate:doc:api:packages:base:file]] and [[:projects:libtate:doc:api:packages:base:filepeer]] are better examples.

==== Native Code ====

Certain files within LibTate contain the word "Native" in their file names. Native classes and code conceptually reside "outside" of the main LibTate code and are used indirectly from within LibTate.

Native code is required in some situations where it neither makes sense to use common code nor to use peer code.

For instance, if we were using DirectX on Win32, we would be required to create a COM class just to use it-- and this can be easily abstracted into an outside native class with no impact on common code.