ceedling 0.25.0 → 0.27.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 373d6a4981555897351460b57dc82e3d90a96d6d
-  data.tar.gz: ff091c1e3c1934718eb19fcab984c3bc169f5b92
+  metadata.gz: 93c488605f82954ab5f2cccb06ecbfc489133c3b
+  data.tar.gz: 5c97c451a98f9fb5c62522f46814f45aba20e4a6
 SHA512:
-  metadata.gz: 0feea9fe999980ad018ea2ec89fb0af54537d3ed1b9b029fa24148f4d7c25fabdf4392a896723046a7b0af46533b8187fa2be902cf3a7a3d6fa633863294122e
-  data.tar.gz: 790254af22bb0d7d28efd37ed3df4d5de2aba82589c0c52abf585ad7732ea43dbff283e861286f34d865acb21870f9aeb25456d6897253a1085a3271d9d718a6
+  metadata.gz: 8cf0b9dbce04687b13d374cfbf214641a72e147093b1c394c67e7e7775c73896c2bc290db3d108174cf8706f0bd378136eefe7540523c7115af2841b89a5695a
+  data.tar.gz: f7575f0950a80118723f6a58fffd361fef164eddb2065ff622641ec1bdb5cbb6aa232149f6821ac495daa7f5086b835fc5c0a1ccd41af14e05271df16ce71fa6

data/README.md

@@ -23,7 +23,7 @@ First make sure Ruby is installed on your system (if it's not already). Then, fr
     > git clone --recursive https://github.com/throwtheswitch/ceedling.git
     > cd ceedling
     > bundle install # Ensures you have all RubyGems needed
-    > bundle execute rake # Run all CMock library tests
+    > bundle exec rake # Run all CMock library tests
 
 If bundler isn't installed on your system or you run into problems, you might have to install it:
 

data/assets/project_as_gem.yml

@@ -62,6 +62,19 @@
 # As [:tools] is blank, gcc will be used (so long as it's in your system path)
 # See documentation to configure a given toolchain for use
 
+# LIBRARIES
+# These libraries are automatically injected into the build process. Those specified as
+# common will be used in all types of builds. Otherwise, libraries can be injected in just
+# tests or releases. These options are MERGED with the options in supplemental yaml files.
+:libraries:
+  :placement: :end
+  :flag: "${1}"  # or "-L ${1}" for example
+  :common: &common_libraries []
+  :test:
+    - *common_libraries
+  :release:
+    - *common_libraries
+
 :plugins:
   :load_paths:
     - "#{Ceedling.load_path}"

data/assets/project_with_guts.yml

@@ -62,6 +62,19 @@
 # As [:tools] is blank, gcc will be used (so long as it's in your system path)
 # See documentation to configure a given toolchain for use
 
+# LIBRARIES
+# These libraries are automatically injected into the build process. Those specified as
+# common will be used in all types of builds. Otherwise, libraries can be injected in just
+# tests or releases. These options are MERGED with the options in supplemental yaml files.
+:libraries:
+  :placement: :end
+  :flag: "${1}"  # or "-L ${1}" for example
+  :common: &common_libraries []
+  :test:
+    - *common_libraries
+  :release:
+    - *common_libraries
+
 :plugins:
   :load_paths:
     - vendor/ceedling/plugins

data/bin/ceedling

@@ -4,7 +4,16 @@
 require 'rubygems'
 require 'fileutils'
 
-unless (File.exists?("project.yml"))
+# Check for the main project file (either the one defined in the ENV or the default)
+main_filepath = ENV['CEEDLING_MAIN_PROJECT_FILE']
+project_found = (!main_filepath.nil? && File.exists?(main_filepath))
+if (!project_found)
+  main_filepath = "project.yml"
+  project_found = File.exists?(main_filepath)
+end
+rakefile_found = (File.exists? "rakefile.rb")
+
+unless (project_found && rakefile_found)
 #===================================== We Do Not Have A Project ================================================
 
   puts "Welcome to Ceedling!"
@@ -21,83 +30,96 @@ unless (File.exists?("project.yml"))
     method_option :nodocs, :type => :boolean, :default => false, :desc => "No docs in vendor directory"
     method_option :as_gem, :type => :boolean, :default => false, :desc => "Create the scaffold using Ceedling as a gem instead of filling in the vendor directory. Implies --no-docs."
     def new(name, silent = false)
-      ceedling_path     = File.join(name, 'vendor', 'ceedling')
-      source_path       = File.join(name, 'src')
-      test_path         = File.join(name, 'test')
-      test_support_path = File.join(name, 'test/support')
-      build_path        = File.join(name, 'build')
-
-      [source_path, test_path, test_support_path, build_path].each do |d|
-        FileUtils.mkdir_p d
-      end
+      copy_assets_and_create_structure(name, silent, false, options[:nodocs], options[:as_gem])
+    end
 
-      unless options[:as_gem]
-        FileUtils.mkdir_p ceedling_path
+    desc "upgrade PROJECT_NAME", "upgrade ceedling for a project (not req'd if gem used)"
+    method_option :nodocs, :type => :boolean, :default => false, :desc => "No docs in vendor directory"
+    def upgrade(name, silent = false)
+      copy_assets_and_create_structure(name, silent, true, options[:nodocs])
+    end
 
-        unless options[:nodocs]
-          doc_path = File.join(ceedling_path, 'docs')
-          FileUtils.mkdir_p doc_path
+    no_commands do
+      def copy_assets_and_create_structure(name, silent=false, force=false, no_docs=false, as_gem=false)
+        ceedling_path     = File.join(name, 'vendor', 'ceedling')
+        source_path       = File.join(name, 'src')
+        test_path         = File.join(name, 'test')
+        test_support_path = File.join(name, 'test/support')
+        build_path        = File.join(name, 'build')
+
+        [source_path, test_path, test_support_path, build_path].each do |d|
+          FileUtils.mkdir_p d
+        end
 
-          in_doc_path = lambda {|f| File.join(doc_path, f)}
+        unless as_gem
+          FileUtils.mkdir_p ceedling_path
+
+          unless no_docs
+            doc_path = File.join(ceedling_path, 'docs')
+            FileUtils.mkdir_p doc_path
+
+            in_doc_path = lambda {|f| File.join(doc_path, f)}
+
+            doc_files = [
+                          'docs/CeedlingPacket.md',
+                          'vendor/c_exception/docs/CException.md',
+                          'vendor/cmock/docs/CMock_Summary.md',
+                          'vendor/unity/docs/UnityAssertionsCheatSheetSuitableforPrintingandPossiblyFraming.pdf',
+                          'vendor/unity/docs/UnityAssertionsReference.md',
+                          'vendor/unity/docs/UnityConfigurationGuide.md',
+                          'vendor/unity/docs/UnityGettingStartedGuide.md',
+                          'vendor/unity/docs/UnityHelperScriptsGuide.md',
+                          'vendor/unity/docs/ThrowTheSwitchCodingStandard.md',
+                        ]
+
+            doc_files.each do |f|
+              copy_file(f, in_doc_path.call(File.basename(f)), :force => force)
+            end
+          end
 
-          doc_files = [
-                        'docs/CeedlingPacket.pdf',
-                        'vendor/c_exception/docs/CExceptionSummary.pdf',
-                        'vendor/cmock/docs/CMock Summary.pdf',
-                        'vendor/unity/docs/UnityAssertionsCheatSheetSuitableforPrintingandPossiblyFraming.pdf',
-                        'vendor/unity/docs/UnityAssertionsReference.pdf',
-                        'vendor/unity/docs/UnityConfigurationGuide.pdf',
-                        'vendor/unity/docs/UnityGettingStartedGuide.pdf',
-                        'vendor/unity/docs/UnityHelperScriptsGuide.pdf',
-                      ]
+          folders = %w{plugins lib}
+          folders.map do |f|
+            {:src => f, :dst => File.join(ceedling_path, f)}
+          end.each do |f|
+            directory(f[:src], f[:dst], :force => force)
+          end
 
-          doc_files.each do |f|
-            copy_file f, in_doc_path.call(File.basename(f))
+          sub_components = [
+            {:src => 'vendor/c_exception/lib/',     :dst => 'vendor/c_exception/lib'},
+            {:src => 'vendor/c_exception/release/', :dst => 'vendor/c_exception/release'},
+            {:src => 'vendor/cmock/config/',        :dst => 'vendor/cmock/config'},
+            {:src => 'vendor/cmock/lib/',           :dst => 'vendor/cmock/lib'},
+            {:src => 'vendor/cmock/release/',       :dst => 'vendor/cmock/release'},
+            {:src => 'vendor/cmock/src/',           :dst => 'vendor/cmock/src'},
+            {:src => 'vendor/constructor/lib/',     :dst => 'vendor/constructor/lib'},
+            {:src => 'vendor/deep_merge/lib/',      :dst => 'vendor/deep_merge/lib'},
+            {:src => 'vendor/diy/lib',              :dst => 'vendor/diy/lib'},
+            {:src => 'vendor/unity/auto/',          :dst => 'vendor/unity/auto'},
+            {:src => 'vendor/unity/release/',       :dst => 'vendor/unity/release'},
+            {:src => 'vendor/unity/src/',           :dst => 'vendor/unity/src'},
+          ]
+
+          sub_components.each do |c|
+            directory(c[:src], File.join(ceedling_path, c[:dst]), :force => force)
           end
         end
 
-        folders = %w{plugins lib}
-        folders.map do |f|
-          {:src => f, :dst => File.join(ceedling_path, f)}
-        end.each do |f|
-          directory f[:src], f[:dst]
+        if as_gem
+          copy_file(File.join('assets', 'project_as_gem.yml'), File.join(name, 'project.yml'), :force => force)
+          copy_file(File.join('assets', 'rakefile_as_gem.rb'), File.join(name, 'rakefile.rb'), :force => force)
+        else
+          copy_file(File.join('assets', 'project_with_guts.yml'), File.join(name, 'project.yml'), :force => force)
+          copy_file(File.join('assets', 'rakefile_with_guts.rb'), File.join(name, 'rakefile.rb'), :force => force)
         end
 
-        sub_components = [
-          {:src => 'vendor/c_exception/lib/',     :dst => 'vendor/c_exception/lib'},
-          {:src => 'vendor/c_exception/release/', :dst => 'vendor/c_exception/release'},
-          {:src => 'vendor/cmock/config/',        :dst => 'vendor/cmock/config'},
-          {:src => 'vendor/cmock/lib/',           :dst => 'vendor/cmock/lib'},
-          {:src => 'vendor/cmock/release/',       :dst => 'vendor/cmock/release'},
-          {:src => 'vendor/cmock/src/',           :dst => 'vendor/cmock/src'},
-          {:src => 'vendor/constructor/lib/',     :dst => 'vendor/constructor/lib'},
-          {:src => 'vendor/deep_merge/lib/',      :dst => 'vendor/deep_merge/lib'},
-          {:src => 'vendor/diy/lib',              :dst => 'vendor/diy/lib'},
-          {:src => 'vendor/unity/auto/',          :dst => 'vendor/unity/auto'},
-          {:src => 'vendor/unity/release/',       :dst => 'vendor/unity/release'},
-          {:src => 'vendor/unity/src/',           :dst => 'vendor/unity/src'},
-        ]
-
-        sub_components.each do |c|
-          directory c[:src], File.join(ceedling_path, c[:dst])
+        unless silent
+          puts "\n"
+          puts "Project '#{name}' #{force ? "upgraded" : "created"}!"
+          puts " - Tool documentation is located in vendor/ceedling/docs" if (not no_docs) and (not as_gem)
+          puts " - Execute 'ceedling help' to view available test & build tasks"
+          puts ''
         end
       end
-
-      if options[:as_gem]
-        copy_file File.join('assets', 'project_as_gem.yml'), File.join(name, 'project.yml')
-        copy_file File.join('assets', 'rakefile_as_gem.rb'), File.join(name, 'rakefile.rb')
-      else
-        copy_file File.join('assets', 'project_with_guts.yml'), File.join(name, 'project.yml')
-        copy_file File.join('assets', 'rakefile_with_guts.rb'), File.join(name, 'rakefile.rb')
-      end
-
-      unless silent
-        puts "\n"
-        puts "Project '#{name}' created!"
-        puts " - Tool documentation is located in vendor/ceedling/docs" if (not options[:nodocs]) and (not options[:as_gem])
-        puts " - Execute 'rake -T' to view available test & build tasks"
-        puts ''
-      end
     end
 
     desc "examples", "list available example projects"
@@ -248,7 +270,7 @@ else
   end
 
   #merge in project settings if they can be found here
-  yaml_options = YAML.load_file('project.yml')
+  yaml_options = YAML.load_file(main_filepath)
   options[:pretend_we_are_gtest] = (yaml_options[:plugins][:enabled].include? :stdout_gtestlike_tests_report) if (yaml_options[:plugins] && yaml_options[:plugins][:enabled])
   if (yaml_options[:paths])
     options[:add_path] = yaml_options[:paths][:tools] || []
@@ -272,6 +294,8 @@ else
         options[:outfile] = "debug.txt"
       when /^help$/
         options[:args] += "-T "
+      when /^project:(\w+)/
+        ENV['CEEDLING_USER_PROJECT_FILE'] = "#{$1}.yml"
       else
         options[:args] += v + " "
     end

data/docs/CeedlingPacket.md

@@ -165,8 +165,8 @@ As a [Ruby gem](http://docs.rubygems.org/read/chapter/1):
 1. [Download and install Ruby](http://www.ruby-lang.org/en/downloads/)
 
 2. Use Ruby's command line gem package manager to install Ceedling:
-   `gem install ceedling` {text:line-break} (Unity, CMock,
-   and CException come along with Ceedling for free)
+   `gem install ceedling`
+   (Unity, CMock, and CException come along with Ceedling for free)
 
 3. Execute Ceedling at command line to create example project
    or an empty Ceedling project in your filesystem (executing
@@ -375,7 +375,7 @@ That is, they must each be specified at the command line each time
 they are needed. For instance, Ceedling's verbosity command
 only affects output at the time it's run.
 
-{text:soft-page-break} Individual test and release file tasks
+Individual test and release file tasks
 are not listed in `-T` output. Because so many files may be present
 it's unwieldy to list them all.
 
@@ -972,11 +972,12 @@ Notes on path grammar within the [:paths] section:
   entry in the [:tools] section
 
 * Wherever multiple path lists are combined for use Ceedling prioritizes
-  path groups as follows: {text:line-break} test paths, support paths,
-  source paths, include paths. This can be useful, for instance, in
-  certain testing scenarios where we desire Ceedling or the compiler to
-  find a stand-in header file before the actual source header file of
-  the same name.
+  path groups as follows:
+  test paths, support paths, source paths, include paths.
+
+  This can be useful, for instance, in certain testing scenarios where
+  we desire Ceedling or the compiler to find a stand-in header file before
+  the actual source header file of the same name.
 
 * Paths:
 
@@ -1270,6 +1271,43 @@ Example [:defines] YAML blurb
     - FEATURE_X=ON
 ```
 
+
+**libraries**: command line defines used in test and release compilation by configured tools
+
+Ceedling allows you to pull in specific libraries for the purpose of release and test builds.
+It has a few levels of support for this. Start by adding a :libraries main section in your
+configuration. In this section, you can optionally have the following subsections:
+
+* `test`:
+
+  Library files that should be injected into your tests when linking occurs.
+  These can be specified as either relative or absolute paths. These files MUST
+  exist when the test attempts to build.
+
+* `source`:
+
+  Library files that should be injected into your release when linking occurs. These
+  can be specified as either relative or absolute paths. These files MUST exist when
+  the release attempts to build UNLESS you are using the subprojects plugin. In that
+  case, it will attempt to build that library for you as a dynamic dependency.
+
+* `system`:
+
+  These libraries are assumed to be in the tool path somewhere and shouldn't need to be
+  specified. The libraries added here will be injected into releases and tests.
+
+* `flag`:
+
+  This is the method of adding an argument for each library. For example, gcc really likes
+  it when you specify “-l${1}”
+
+Notes:
+
+* If you've specified your own link step, you are going to want to add ${4} to your argument
+list in the place where library files should be added to the command call. For gcc, this is
+often the very end. Other tools may vary.
+
+
 **flags**: configure per-file compilation and linking flags
 
 Ceedling tools (see later [:tools] section) are used to configure
@@ -1552,14 +1590,14 @@ A Ceedling tool has a handful of configurable elements:
    form a name from the tool's YAML entry name)
 
 4. [:stderr_redirect] - Control of capturing $stderr messages
-   {:none, :auto, :win, :unix, :tcsh}. {text:line-break}
+   {:none, :auto, :win, :unix, :tcsh}.
    Defaults to :none if unspecified; create a custom entry by
    specifying a simple string instead of any of the available
    symbols.
 
 5. [:background_exec] - Control execution as background process
-   {:none, :auto, :win, :unix}. {text:line-break} Defaults
-   to :none if unspecified.
+   {:none, :auto, :win, :unix}.
+   Defaults to :none if unspecified.
 
 
 Tool Element Runtime Substitution
@@ -1637,9 +1675,9 @@ Example [:tools] YAML blurbs
      :executable: compiler              #exists in system search path
      :name: 'acme test compiler'
      :arguments:
-        - -I"$”: COLLECTION_PATHS_TEST_TOOLCHAIN_INCLUDE               #expands to -I search paths
-        - -I"$”: COLLECTION_PATHS_TEST_SUPPORT_SOURCE_INCLUDE_VENDOR   #expands to -I search paths
-        - -D$: COLLECTION_TEST_DEFINES  #expands to all -D defined symbols
+        - -I"$": COLLECTION_PATHS_TEST_TOOLCHAIN_INCLUDE               #expands to -I search paths
+        - -I"$": COLLECTION_PATHS_TEST_SUPPORT_SOURCE_INCLUDE_VENDOR   #expands to -I search paths
+        - -D$: COLLECTION_DEFINES_TEST_AND_VENDOR  #expands to all -D defined symbols
         - --network-license             #simple command line argument
         - -optimize-level 4             #simple command line argument
         - "#{`args.exe -m acme.prj`}"   #in-line ruby sub to shell out & build string of arguments
@@ -1673,7 +1711,8 @@ Resulting command line constructions from preceding example [:tools] YAML blurbs
 
 [notes: (1.) "arg-foo arg-bar arg-baz" is a fabricated example
 string collected from $stdout as a result of shell execution
-of args.exe {text:line-break} (2.) the -c and -o arguments are
+of args.exe
+(2.) the -c and -o arguments are
 fabricated examples simulating a single compilation step for
 a test; ${1} & ${2} are single files]
 
@@ -1698,9 +1737,8 @@ Notes:
   builds
 
 * "COLLECTION_" indicates that Ceedling did some work to assemble
-  the list. For instance, expanding path globs, {text:soft-page-break}
-  combining multiple path globs into a convenient summation,
-  etc.
+  the list. For instance, expanding path globs, combining multiple
+  path globs into a convenient summation, etc.
 
 * At present, $stderr redirection is primarily used to capture
   errors from test fixtures so that they can be displayed at the
@@ -1776,11 +1814,11 @@ Notes:
   only useful for advanced features not yet documented.
 
 * Wherever multiple path lists are combined for use Ceedling prioritizes
-  path groups as follows: {text:line-break} test paths, support paths,
-  source paths, include paths. This can be useful, for instance, in
-  certain testing scenarios where we desire Ceedling or the compiler to
-  find a stand-in header file before the actual source header file of
-  the same name.
+  path groups as follows: test paths, support paths, source paths, include
+  paths.
+  This can be useful, for instance, in certain testing scenarios
+  where we desire Ceedling or the compiler to find a stand-in header file
+  before the actual source header file of the same name.
 
 
 **plugins**: Ceedling extensions

data/docs/ThrowTheSwitchCodingStandard.md

@@ -0,0 +1,207 @@
+# ThrowTheSwitch.org Coding Standard
+
+Hi. Welcome to the coding standard for ThrowTheSwitch.org. For the most part,
+we try to follow these standards to unify our contributors' code into a cohesive
+unit (puns intended). You might find places where these standards aren't
+followed. We're not perfect. Please be polite where you notice these discrepancies
+and we'll try to be polite when we notice yours.
+
+;)
+
+
+## Why Have A Coding Standard?
+
+Being consistent makes code easier to understand. We've made an attempt to keep
+our standard simple because we also believe that we can only expect someone to
+follow something that is understandable. Please do your best.
+
+
+## Our Philosophy
+
+Before we get into details on syntax, let's take a moment to talk about our
+vision for these tools. We're C developers and embedded software developers.
+These tools are great to test any C code, but catering to embedded software has
+made us more tolerant of compiler quirks. There are a LOT of quirky compilers
+out there. By quirky I mean "doesn't follow standards because they feel like
+they have a license to do as they wish."
+
+Our philosophy is "support every compiler we can". Most often, this means that
+we aim for writing C code that is standards compliant (often C89... that seems
+to be a sweet spot that is almost always compatible). But it also means these
+tools are tolerant of things that aren't common. Some that aren't even
+compliant. There are configuration options to override the size of standard
+types. There are configuration options to force Unity to not use certain
+standard library functions. A lot of Unity is configurable and we have worked
+hard to make it not TOO ugly in the process.
+
+Similarly, our tools that parse C do their best. They aren't full C parsers
+(yet) and, even if they were, they would still have to accept non-standard
+additions like gcc extensions or specifying `@0x1000` to force a variable to
+compile to a particular location. It's just what we do, because we like
+everything to Just Work™.
+
+Speaking of having things Just Work™, that's our second philosophy. By that, we
+mean that we do our best to have EVERY configuration option have a logical
+default. We believe that if you're working with a simple compiler and target,
+you shouldn't need to configure very much... we try to make the tools guess as
+much as they can, but give the user the power to override it when it's wrong.
+
+
+## Naming Things
+
+Let's talk about naming things. Programming is all about naming things. We name
+files, functions, variables, and so much more. While we're not always going to
+find the best name for something, we actually put quite a bit of effort into
+finding *What Something WANTS to be Called*™.
+
+When naming things, we more or less follow this hierarchy, the first being the
+most important to us (but we do all four whenever possible):
+1. Readable
+2. Descriptive
+3. Consistent
+4. Memorable
+
+
+#### Readable
+
+We want to read our code. This means we like names and flow that are more
+naturally read. We try to avoid double negatives. We try to avoid cryptic
+abbreviations (sticking to ones we feel are common).
+
+
+#### Descriptive
+
+We like descriptive names for things, especially functions and variables.
+Finding the right name for something is an important endeavor. You might notice
+from poking around our code that this often results in names that are a little
+longer than the average. Guilty. We're okay with a tiny bit more typing if it
+means our code is easier to understand.
+
+There are two exceptions to this rule that we also stick to as religiously as
+possible:
+
+First, while we realize hungarian notation (and similar systems for encoding
+type information into variable names) is providing a more descriptive name, we
+feel that (for the average developer) it takes away from readability and
+therefore is to be avoided.
+
+Second, loop counters and other local throw-away variables often have a purpose
+which is obvious. There's no need, therefore, to get carried away with complex
+naming. We find i, j, and k are better loop counters than loopCounterVar or
+whatnot. We only break this rule when we see that more description could improve
+understanding of an algorithm.
+
+
+#### Consistent
+
+We like consistency, but we're not really obsessed with it. We try to name our
+configuration macros in a consistent fashion... you'll notice a repeated use of
+UNITY_EXCLUDE_BLAH or UNITY_USES_BLAH macros. This helps users avoid having to
+remember each macro's details.
+
+
+#### Memorable
+
+Where ever it doesn't violate the above principles, we try to apply memorable
+names. Sometimes this means using something that is simply descriptive, but
+often we strive for descriptive AND unique... we like quirky names that stand
+out in our memory and are easier to search for. Take a look through the file
+names in Ceedling and you'll get a good idea of what we are talking about here.
+Why use preprocess when you can use preprocessinator? Or what better describes a
+module in charge of invoking tasks during releases than release_invoker? Don't
+get carried away. The names are still descriptive and fulfill the above
+requirements, but they don't feel stale.
+
+
+## C and C++ Details
+
+We don't really want to add to the style battles out there. Tabs or spaces?
+How many spaces? Where do the braces go? These are age-old questions that will
+never be answered... or at least not answered in a way that will make everyone
+happy.
+
+We've decided on our own style preferences. If you'd like to contribute to these
+projects (and we hope that you do), then we ask if you do your best to follow
+the same. It will only hurt a little. We promise.
+
+
+#### Whitespace
+
+Our C-style is to use spaces and to use 4 of them per indent level. It's a nice
+power-of-2 number that looks decent on a wide screen. We have no more reason
+than that. We break that rule when we have lines that wrap (macros or function
+arguments or whatnot). When that happens, we like to indent further to line
+things up in nice tidy columns.
+
+```C
+    if (stuff_happened)
+    {
+        do_something();
+    }
+```
+
+
+#### Case
+
+- Files - all lower case with underscores.
+- Variables - all lower case with underscores
+- Macros - all caps with underscores.
+- Typedefs - all caps with underscores. (also ends with _T).
+- Functions - camel cased. Usually named ModuleName_FuncName
+- Constants and Globals - camel cased.
+
+
+#### Braces
+
+The left brace is on the next line after the declaration. The right brace is
+directly below that. Everything in between in indented one level. If you're
+catching an error and you have a one-line, go ahead and to it on the same line.
+
+```C
+    while (blah)
+    {
+        //Like so. Even if only one line, we use braces.
+    }
+```
+
+
+#### Comments
+
+Do you know what we hate? Old-school C block comments. BUT, we're using them
+anyway. As we mentioned, our goal is to support every compiler we can,
+especially embedded compilers. There are STILL C compilers out there that only
+support old-school block comments. So that is what we're using. We apologize. We
+think they are ugly too.
+
+
+## Ruby Details
+
+Is there really such thing as a Ruby coding standard? Ruby is such a free form
+language, it seems almost sacrilegious to suggest that people should comply to
+one method! We'll keep it really brief!
+
+
+#### Whitespace
+
+Our Ruby style is to use spaces and to use 2 of them per indent level. It's a
+nice power-of-2 number that really grooves with Ruby's compact style. We have no
+more reason than that. We break that rule when we have lines that wrap. When
+that happens, we like to indent further to line things up in nice tidy columns.
+
+
+#### Case
+
+- Files - all lower case with underscores.
+- Variables - all lower case with underscores
+- Classes, Modules, etc - Camel cased.
+- Functions - all lower case with underscores
+- Constants - all upper case with underscores
+
+
+## Documentation
+
+Egad. Really? We use markdown and we like pdf files because they can be made to
+look nice while still being portable. Good enough?
+
+
+*Find The Latest of This And More at [ThrowTheSwitch.org](https://throwtheswitch.org)*