Project Organization

Originally posted,

I find it remarkable that in most places that I have worked people have spent little time or thought about the actually file layout of their projects. Over time I have developed a rather strong preference for the file layout that I use because of the number of times that other methods have created huge headaches for me at the worst possible times. Specifically, I am a strong believer of out-of-source compilations. Let me start out with an explanation of the setup used by TGS. It pretty much follows that standard Unix model. From the root directory I have two source directories: /inc for include files and /src for the source files. Each of these contain sub-directories as necessary for each system, but only the root for each of these paths is included in the compilation settings (so /inc is part of the search path but /inc/TgS COMMON would not be). This means that users need to relative path sub-directory stored files, but I wanted to retain the clarity of where files were coming from during the compilation phase. There are two intermediate directories: /prj holds the project and solution files that are generated by CMake (see above) for interacting with the source files and /obj that contains all of the compiler intermediate files. Finally, I have two target directories: /bin to hold all executable files and /lib to hold all static libraries. Shared libraries or DLLs would be stored in the /bin directory but I currently do not use them in any of my projects. I have three non-compilation related directories: /web holds the contents of the TGS related web content for this web page, /tst holds the testing environment and its files for the unit tests for the solution and /doc for documents related to TGS and studies that I have done in regards to performance profiling to determine some of my coding decisions.

Well, that is all well and good, but why is this a clean system that in-source compilations or just a random collection of files. I have found it necessary at different times in my career to have to do various full-project diffs and changes, or the need to move entire code trees around do to major code initiatives. Every time this happens, the GBs of data attached to the intermediate files because a huge slow down for all of these operations. It is not even always desirable or easy to remove all of these files. Removing them would require a complete recompile the next time you use the project and if this process is iterative then you’ve added significant amount of time and work to the process. I have also ran into many problems with compilers related to PCHs and incomplete cleans creating weird and simply wrong compilations. The ability to clean the environment by blowing away the one obj directory is so nice and easy that it would be sufficient reasons by itself for setting up out-of-source. There is also a good psychological reason for separating things out into separate areas (like your lights and dark when doing laundry). One final reason I found was that it did simply the porting process when I needed to move files between multiple platforms, and not having to individually clean through object files made it an easy process.