Read Me

Author: Track.
Last change: 25-May-2006.

Preface
-------

This file describes many useful things one need to know
before trying to understand the code, especially
if one wish to hack the code.

PLEASE read this document to the end before trying to
look at the code, especially if you wish to change
the code.

Also, please read the project design doc ("./doc/design.txt")
before attempting to hack the code.

Several conventions are presented here which all the code
in this project must adhere to.

By knowing these conventions it'll be easier for you to find
the file or function you look for.

If you add new files or modules, or hack existing code,
PLEASE be sure to adhere to the conventions presented here.
This will ensure the code is always in good shape and is
pleasure to work with!


Table Of Contents
-----------------

1. Directories layout and file placement
2. File placement and naming conventions
2.1 Header files
2.2 Source files
2.3 File name conventions
2.4 Directory names conventions
3. Coding conventions
3.1 Naming conventions in sources.
3.1.1 Class naming conventions.
3.1.2 Class data field naming conventions. 
3.1.3 Class method naming conventions.
3.1.4 Function naming conventions.
3.1.5 Global variables naming conventions.
3.1.6 Macro naming conventions.
3.2 Preferred C code layout.


CHAPTER 1. Directories layout and file placement

This chapter explains the directory layout of the OpenEm source tree,
and will help you find the files you need quickly.

The project sources are divided into modules.

Each module have its unique name, and consists of interface,
implementation, and documentation parts.

* Public inter-module interfaces (header files) are located
  under "./include".
* Implementation (*.cpp) files, as well as private headers
  (see CHAPTER 2.1) are located under "./src/module_name/".
* Documentation, if any, is located under "./doc/module_name/".

If module is logically under another module it may be placed in
a subdirectory.
For example: "/cpu/I8086" is module named "I8086", which logically
comes under module "cpu".

Under these three main directories, there are subdirectories per module.
For example module "arch/ibmpc" would occupy three directories:
* ./include/arch/ibmpc/ (files: ibmpc.h)
* ./src/arch/ibmpc/ (files: ibmpc.cpp, ibmpc_funcs.cpp, ibmpc_funcs.h)
* ./doc/arch/ibmpc/ (files: ibmpc-arch.doc, dma.doc, video.doc)

The subdirectories like "arch" themselves (There are three of them,
under "./include", under "/src" and under "/doc") will most probably
contain only subdirectories for sub-modules, but files common to all
architectures may occasionally be located there too.

In addition to the three directories described above, there are additional
directories:
./build           : Project and make files for various platforms and IDEs.
./build/msvc6     : Microsoft Visual Studio 6 projects.
./build/msvc7     : Microsoft Visual Studio 7 projects.
./build/linux     : Linux port projects.
./obj/debug       : Debug version object files (and maybe other stuff) are placed here.
./obj/release     : Release version object files (and maybe other stuff) are placed here.
./lib/debug       : Static library files ("*.lib") produced by compilation
                    are placed here (debug version).
./lib/release     : Static library files ("*.lib") produced by compilation
                    are placed here (release version).
./bin             : Output executables (and .DLLs) produced by compilation
                    are placed here.
./ext             : External (third party) libraries required by the project
                    are placed here.
                    Example: SDL framework.
                    In general, under ./ext there should be subdirectories
                    "lib", "include", and (only if sources are available),
					"src".
./ext/lib      : .lib files provided by third party libraries.
./ext/include  : header files provided by third party libraries.
./ext/src      : source files (if available) of third party libraries.

TODO::
- Think about how (and whether) to divide debug/release EXECUTABLES (in /bin).
- Maybe there are compilers out there which place .o files in the same
  directories where are the sources. I don't like to let /src/ directory
  be cluttered. Ideally I'd like to let it (and /include) to be read-only
  during compilation.
- Think about the trash compilers place in various places (symbols, debug info,
  .MAP files, etc...).
- Maybe define what should come under "./ext" more precisely?
- What about separate debug and release versions of third party libraries under
  "./ext"? Use the same convention as for "obj" and "lib" directories?

CHAPTER 2. File placement and naming conventions
All modules in this project adhere to file placement and naming conventions.

CHAPTER 2.1 Header files
There are two kinds of header files ("*.h"):
* Public (inter-module) interfaces.
  Located at "/include/<module_name>/*.h".
  These are visible not only to the module itself, but also to other
  modules which might use this module.
* Private (module internal) interfaces.
  Located at "/src/<module_name>/*.h" (together with .CPP sources).
  The sole purpose of these header files is to contain declarations
  shared by several "*.cpp" source files in the same module.
  The declarations in these private headers are not designed to be
  visible by other modules.
  These headers are intentionally NOT placed under "/include"
  directory in order to avoid pollution there and to make
  inter-module APIs more clear and easier to study to the
  occasional hacker.

  Again, ONLY those headers describing public interfaces of given module
  should be placed in module subdirectory under "/include".
  All other header files are PRIVATE to the module and must go
  into module subdirectory under "/src" direcotry.
  PLEASE keep this convention in order to keep the source code
  maintainable.

CHAPTER 2.2 Source files
The source files ("*.cpp") are located under "/src/<module_name>".
They contain implementation code.

Often, module would contain more than one source file.
Also, often source files need internal declarations to be shared among them.
These shared declarations are placed in header files which are private
to the module and visible to the source (".cpp") files of that specific
module ONLY. (Also see CHAPTER 2.1 regarding private header files).

CHAPTER 2.3 File name conventions
In order to keep the source code file names consistent across the whole
project, and to make hacking the project easier, there are some
conventions regarding naming of files.

Note that these conventions are not as important as the file placement,
but it's still good to keep the file names pretty :)

* Try to keep file names in lower case, unless specifically needed
  (say, you must name header file after name of the CPU and
   cpu is called I8086 (with capital I)).
  This is especially important to support UNIX systems which are
  case sensitive. For example if one #include's file with invalid case
  in it's name under Windows - it WILL work for him (at least under
  Visual Studio). On the other hand, someone using Unix will gen an
  error compiling such code!
  So, PLEASE do not use capital letters in file names unless really
  necessary!
* If you want file name to contain more than one word, use underscore
  between them (ex: "vga_video.h").
  NEVER work with filenames containing spaces as these often tough
  for many compilation tools to handle!
  Also, do NOT use CamelCase-style names such as "SoundBlasterDma.h",
  use "sound_blaster_dma.h" instead.
  Remember: avoid capital letters in file names unless really necessary.
* Please keep file names reasonably short, but not cryptic!
  Names such as "pds.h" do not tell much, while "pc_dma_sys.h"
  describes file purpose much better.

CHAPTER 2.4 Directory names conventions
Directory names, like file names, should be in lower case unless capital
letters are REALLY needed (like, when you name directory after real
name of some CPU chip, for example "I686").
It's important to have mostly lower case directory names for the same
purpose as having them for files: to allow painless interoperability
between case insensitive Windows systems and case sensitive Unix systems.

CHAPTER 3. Coding conventions
This chapter describes coding conventions developers should strive to
adhere to. Having same coding conventions across all the project codebase
helps a lot in maintaining the project.

CHAPTER 3.1 Naming conventions in sources.
This chapter describes considerations when naming things (variables, macros, 
classes, functions, etc...).

CHAPTER 3.1.1 Class naming conventions.
TODO:: describe how to name classes.
CHAPTER 3.1.2 Class data field naming conventions. 
TODO:: describe how to name data fields in classes.
CHAPTER 3.1.3 Class method naming conventions.
TODO:: describe how to name methods in classes.
CHAPTER 3.1.4 Function naming conventions.
TODO:: describe how to name functions which are not part of any class.
CHAPTER 3.1.5 Global variables naming conventions.
TODO:: describe how to name global variables (if used).
CHAPTER 3.1.6 Macro naming conventions.
TODO:: describe how to name macros (if used).
CHAPTER 3.2 Preferred C code layout.
TODO:: Describe preferred C code layout, such as where
       to place curly braces { and }, whether to
	   place "else" on separate line, etc...

TODO:: Anything else to add here? Maybe word or two about modularity?
Regarding CHAPTER 3: maybe it should go to design doc, and not in this README?

NOTE:: The ideas here come mostly from Unix filesystem
       conventions, but aim at clarity and easier code maintenance
       for the long run.