Waji's Standards
Posted: Thu Oct 09, 2014 4:16 am
I'm aware there are plenty of standards to choose from. I just don't like any of them. So of course, I'm going to bask in the irony of making my own.
/basking commences
One thing I happened to realize is the lack of organized criticism of any of the Unix standards despite the fact that anyone can look at them and find a mountain of things to complain about. I almost get the feeling there is some shadey group of 1337 linus worshipping hackers pounding away at their keyboards in their dank mother's basements. Insomniacs overdosed on WoW...Their skin, pale from the lack of nurishment from sunlight. Eyes burning, lights dim, monitors glaring off their glasses...[reflecting on personal experience] Where the hell was I going with this....
Anyhow, I'm going to post a few bs standards every now and then, and I want you guys to tell me what you think or any suggestions you may have. Don't be afraid to roast me, I'm a level 69 magus with oakflesh, I can take it.
Project Structure
Goals
Presentation
Details
Projects Cannot Contain Other Projects
There are several reasons for this. Firstly, it just makes the directory structure easier to navigate. Secondly, this prevents the issue of "recursive make considered harmful". Thirdly, it makes the structure more compatable with ide's. The solution should not contain any directories aside from the project directories.
Assets and Resources
With C and C++ projects, there never really was a specific directory for resources that should be embedded into the object file itself. Some people just use 'res' or 'rsc'. Assets to be distributed with the application were usually stored in a 'share' directory. The naming scheme was borrowed from the Filesystem Hierarchy Standard. The problem with this is that almost everything in the FHS is either abbreviated or conjugated in some way, and the structure recursively follows the same pattern which while easy to remember also makes it easy to get lost. A better approach in my opinion would be to use a different directory structure to help differentiate it from the rest of the filesystem and just use symbolic links if backwards compatibility is desired.
Localization
While gettext is the defacto standard for localization, it's not very useful when it comes to some embedded systems (especially when the filesystem doesn't contain file names). So in addition to localizing messages, I figured it'd be a good idea to consider the localization of pointers as well. Obviously, localized pointers would be statically linked though unlike messages. Note that both the asset and locale directories contain the input files. Ie. /locale/messages would contain the .pot files for gettext. The output files of these 2 directories is placed in /output/<build>/assets' and '/output/<build>/locale'.
Project Outline
This directory is used for keeping track of information about the project such as the budget, goals, ideas, etc. Ie. Files like README, TODO, AUTHORS, ChangeLog, etc. from the usual C/C++ directory structure would go here.
Project Output
The output directory contains a different subdirectory for each build type. Ie. debug, release, etc.
Scripts
These are scripts used when building the project. They're particularly useful for unit tests or for projects that require multiple passes to build; like the gcc.
Headers and Imports
This was changed from 'include' and 'lib' to 'shared/headers' and 'shared/imports' for two reasons. First is to make a more clear distinction about what the directories are for. People have a bad habit of putting headers in the include directory that don't belong there. Second is to clear up vague terminology. The term 'library' can mean many things; static, shared, dynamic, runtime, etc. But the only types of files that should be in it are libraries used for linking. Additionally, in some programming languages like C#, the libraries contain metadata to use when compiling code rather than requiring the programmer to include headers.
Shared Objects
This directory was added out of consideration for static linking. Sometimes, it just isn't practical to create a static library. For example, you may only need reuse a single .o file, use a flat binary stub for something, or have multiple static libraries that use the same .o files.
Summary
I'm not claiming this is the holy grail or something, but I believe it's more elegant and easier to maintain than what is currently considered the 'standard'. My focus was to come up with something modular that would compliment the use of makefiles and shell scripts; but would be abstract enough to be useful for projects that go beyond simply programming.
Well, there you have it. Hit me peeps, my body is ready.
/basking commences
One thing I happened to realize is the lack of organized criticism of any of the Unix standards despite the fact that anyone can look at them and find a mountain of things to complain about. I almost get the feeling there is some shadey group of 1337 linus worshipping hackers pounding away at their keyboards in their dank mother's basements. Insomniacs overdosed on WoW...Their skin, pale from the lack of nurishment from sunlight. Eyes burning, lights dim, monitors glaring off their glasses...[reflecting on personal experience] Where the hell was I going with this....
Anyhow, I'm going to post a few bs standards every now and then, and I want you guys to tell me what you think or any suggestions you may have. Don't be afraid to roast me, I'm a level 69 magus with oakflesh, I can take it.
Project Structure
Goals
- The directory names should be human recognizable
- The structure must be simple to navigate
- The structure must be considerate of the planning process; with goals, rules, etc.
Presentation
Code: Select all
solution
+- project1
| +- assets project assets
| | '- internal '- internal assets
| +- locale project localization
| | +- messages '- localized messages
| | '- pointers '- localized pointers
| +- outline project outline
| +- output project output
| | '- <build> '- project build
| +- scripts scripts used for building the project
| | +- passes +- build passes
| | '- tests '- build tests
| +- shared shared project data
| | +- headers +- code headers
| | +- imports +- code imports
| | '- objects '- code objects
| '- source project source
'- project2
...Projects Cannot Contain Other Projects
There are several reasons for this. Firstly, it just makes the directory structure easier to navigate. Secondly, this prevents the issue of "recursive make considered harmful". Thirdly, it makes the structure more compatable with ide's. The solution should not contain any directories aside from the project directories.
Assets and Resources
With C and C++ projects, there never really was a specific directory for resources that should be embedded into the object file itself. Some people just use 'res' or 'rsc'. Assets to be distributed with the application were usually stored in a 'share' directory. The naming scheme was borrowed from the Filesystem Hierarchy Standard. The problem with this is that almost everything in the FHS is either abbreviated or conjugated in some way, and the structure recursively follows the same pattern which while easy to remember also makes it easy to get lost. A better approach in my opinion would be to use a different directory structure to help differentiate it from the rest of the filesystem and just use symbolic links if backwards compatibility is desired.
Localization
While gettext is the defacto standard for localization, it's not very useful when it comes to some embedded systems (especially when the filesystem doesn't contain file names). So in addition to localizing messages, I figured it'd be a good idea to consider the localization of pointers as well. Obviously, localized pointers would be statically linked though unlike messages. Note that both the asset and locale directories contain the input files. Ie. /locale/messages would contain the .pot files for gettext. The output files of these 2 directories is placed in /output/<build>/assets' and '/output/<build>/locale'.
Project Outline
This directory is used for keeping track of information about the project such as the budget, goals, ideas, etc. Ie. Files like README, TODO, AUTHORS, ChangeLog, etc. from the usual C/C++ directory structure would go here.
Project Output
The output directory contains a different subdirectory for each build type. Ie. debug, release, etc.
Scripts
These are scripts used when building the project. They're particularly useful for unit tests or for projects that require multiple passes to build; like the gcc.
Headers and Imports
This was changed from 'include' and 'lib' to 'shared/headers' and 'shared/imports' for two reasons. First is to make a more clear distinction about what the directories are for. People have a bad habit of putting headers in the include directory that don't belong there. Second is to clear up vague terminology. The term 'library' can mean many things; static, shared, dynamic, runtime, etc. But the only types of files that should be in it are libraries used for linking. Additionally, in some programming languages like C#, the libraries contain metadata to use when compiling code rather than requiring the programmer to include headers.
Shared Objects
This directory was added out of consideration for static linking. Sometimes, it just isn't practical to create a static library. For example, you may only need reuse a single .o file, use a flat binary stub for something, or have multiple static libraries that use the same .o files.
Summary
I'm not claiming this is the holy grail or something, but I believe it's more elegant and easier to maintain than what is currently considered the 'standard'. My focus was to come up with something modular that would compliment the use of makefiles and shell scripts; but would be abstract enough to be useful for projects that go beyond simply programming.
Well, there you have it. Hit me peeps, my body is ready.