comet-build 0.1.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 670917577b152678f86951ca8a0e93a869913be0
+  data.tar.gz: c748f50c7ae73456251b01826c8ddb8d4f257b3d
+SHA512:
+  metadata.gz: a6d1fcb5c2fe0ea3d5d3cbfa1a13c85b63cae9ae8e45405f61a705d5f899f9812a32b0bc7691eec9cbc22ae3a945550467d1c5c8bdea87b3654512ac3ee24cc5
+  data.tar.gz: 4cab4c5ecec92d24f0ecc1fd83a9ef6a7412d8b7ec90c5241f3cbd697673c847b54f443875227131dd56e66aea158f64a14f2997e44f0f918a2eed9cc425ae8f

data/.gitignore

@@ -0,0 +1,59 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+# Used by dotenv library to load environment variables.
+# .env
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+*.bridgesupport
+build-iPhoneOS/
+build-iPhoneSimulator/
+
+## Specific to RubyMotion (use of CocoaPods):
+#
+# We recommend against adding the Pods directory to your .gitignore. However
+# you should judge for yourself, the pros and cons are mentioned at:
+# https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control
+#
+# vendor/Pods/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+# Gemfile.lock
+# .ruby-version
+# .ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc
+
+# avoid checking in temporary build folders
+.comet
+
+# various backup files from editors
+*~
+~*
+.swp*
+.swo*

data/.rspec

@@ -0,0 +1 @@
+-c -f documentation --order random

data/.rubocop.yml

@@ -0,0 +1,14 @@
+require: rubocop-rspec
+
+AllCops:
+  Exclude:
+    - '**/*/comet.rb'
+
+Style/Documentation:
+  Enabled: false
+
+Style/SpecialGlobalVars:
+  Enabled: false
+
+Style/ClassAndModuleChildren:
+  Enabled: false

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,58 @@
+PATH
+  remote: .
+  specs:
+    comet (0.1.0)
+      require_all
+      slop
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.3.0)
+    diff-lcs (1.3)
+    parallel (1.12.0)
+    parser (2.4.0.0)
+      ast (~> 2.2)
+    powerpack (0.1.1)
+    rainbow (2.2.2)
+      rake
+    rake (12.0.0)
+    require_all (1.4.0)
+    rspec (3.6.0)
+      rspec-core (~> 3.6.0)
+      rspec-expectations (~> 3.6.0)
+      rspec-mocks (~> 3.6.0)
+    rspec-core (3.6.0)
+      rspec-support (~> 3.6.0)
+    rspec-expectations (3.6.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.6.0)
+    rspec-mocks (3.6.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.6.0)
+    rspec-support (3.6.0)
+    rubocop (0.49.1)
+      parallel (~> 1.10)
+      parser (>= 2.3.3.1, < 3.0)
+      powerpack (~> 0.1)
+      rainbow (>= 1.99.1, < 3.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (~> 1.0, >= 1.0.1)
+    rubocop-rspec (1.15.1)
+      rubocop (>= 0.42.0)
+    ruby-progressbar (1.8.1)
+    slop (4.5.0)
+    unicode-display_width (1.3.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.7)
+  comet!
+  rake (~> 12.0)
+  rspec
+  rubocop-rspec
+
+BUNDLED WITH
+   1.15.3

data/LICENSE

@@ -0,0 +1,9 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Thomas Bénéteau
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,311 @@
+Comet
+=====
+
+Comet is a no-nonsense build tool primarily oriented towards embedded or cross-compiled applications written in languages that can compile to LLVM bitcode, such as C, C++, D, etc. It adheres to four core principles:
+
+ * **Simplicity**: Your build tool should be your friend, not your enemy. Comet does not force you to learn crazy languages and use strange idiosyncracies to build your program, instead exposing a simple and pleasant DSL to describe how you want your program built.
+
+ * **Predictability**: Good software should be predictable, so Comet requires you to specify every aspect of your build configuration, leaving no opportunity for hazardous defaults to sneak in. Comet also steers you away from bad practices by enforcing sane conventions.
+
+* **Focus**: Comet does not try to deal with the rest of your release process, such as generating documentation, preparing artifacts, running tests, and so on. Comet is concerned solely with the process of building your source files into executables, and is easily integrated into other scripts.
+
+ * **Performance**: Due to Comet's design and LLVM integration, you get many features for free such as whole-program optimization, cross-compilation and multi-language support. Comet itself is also efficient and does not slow down your builds.
+
+Functionally, Comet is a Makefile generator which accepts a domain-specific language from a build file, produces a Makefile, and executes it, placing all intermediate files inside a hidden `.comet` temporary directory. The only thing you need to do as a developer is write your `comet.rb` build file and add `.comet` to your gitignore file.
+
+**WARNING**: this software is still in the testing phase, use in production at your own risk. Improvement suggestions and pull requests are welcome and appreciated. Currently only the C language is supported (C++ will be added shortly) and the tool probably only works on Linux as of now, but just a couple parts of the code are OS-dependent.
+
+Installation
+------------
+
+    gem install comet-build
+
+Comet wraps Make, consuming only two command line arguments and forwarding the rest.
+
+  - `-f PATH`: search for the build file at the specified path instead of `comet.rb`
+  - `-s`: don't execute the generated Makefile, print it to standard output instead
+
+Comet generates the following convenience Make targets:
+
+ - `all`: build absolutely everything (this is also the default target)
+ - `clean`: delete the `.comet` folder (there is no invididual clean)
+
+It doesn't matter where in your source tree you invoke Comet, as it will walk its way back up the filesystem looking for your build file until it hits a filesystem boundary, similar to Git. Furthermore, the `.comet` folder is always next to the build file Comet is operating on.
+
+No external (non-Ruby) dependencies are required for *generating* the Makefile. However, the Makefile itself expects the Clang and LLVM tools to be installed in the user's path. If cross-compiling, it also requires the appropriate binutils toolchains to be installed, e.g. `arm-none-eabi` for embedded ARM software. When executing the Makefile, Comet will call out to the system's Make implementation, which can be overridden with the `MAKE` environment variable.
+
+Supported Languages
+-------------------
+
+Language support for compiling source files is shown below. Adding support for a language consists of supplying a suitable DSL object for it, and implementing a Make rule to compile source files of this language into a single LLVM bitcode file. This Make rule will need to call out to language-specific compilers and other tools, which should be documented in the table below.
+
+| Language | DSL keyword | Required compilers |
+| -------- | ----------- | ------------------ |
+| *Native* | `:native`   | None (link-only)   |
+| C        | `:c`        | Clang              |
+
+Native languages are those for which the source code is either already LLVM bitcode, or is already in a lower representation than LLVM IR, such as assembly. These will be passed directly to the linker after compiled LLVM bitcode, therefore:
+
+ * they cannot reference symbols from non-native source files
+ * they must be given in the usual "reverse dependency" order
+ * they must actually be accepted by the linker as input files
+
+Planned features
+----------------
+
+ - C++ language support
+ - Windows support
+ - Clarification of linker parameters (triple, isa, cpu)
+ - Ability to import other build files recursively
+ - Integration with other build systems when linking vendored libraries
+
+Build File Syntax
+-----------------
+
+The Ruby DSL used for describing your program is very straightforward. You begin by defining three high-level structures:
+
+ - `software`, describing hardware-agnostic source code
+ - `hardware`, describing source code tied to a specific device
+ - `firmware`, describing software/hardware combinations of interest
+
+All paths in the build file are relative to the build file's location. Spaces in filenames are **not** supported. The ordering of distinct directives is unimportant, i.e. you do not have to specify them in this order. The relative ordering of some directives, however, is meaningful, such as library imports which are passed to the linker in order of appearance.
+
+Note that Ruby allows you to write blocks with either `do` and `end` or curly braces. Curly brace blocks are not always usable syntactically in some cases, but the DSL does not hit any of them, so just use whichever style you prefer - `do` and `end` will be used throughout this section.
+
+### Software Directive
+
+A `software` directive must be uniquely named, and may include any number of `source` directives (but at least one) describing the source code contained under it. It may also include any number of dependencies, which can be either software or hardware directives, referenced by name. Software directives cannot include *native* source directives.
+
+#### Grammar
+
+```ruby
+software 'name', depends: ['dep1', 'dep2', ...] do
+  # source directives
+end
+```
+
+#### Examples
+
+```ruby
+software 'i2c', depends: ['i2c-hal'] do
+  source language: :c, headers: 'include' do
+    import 'src/drivers/i2c.c'
+  end
+end
+```
+
+### Hardware Directive
+
+A `hardware` directive need not be uniquely named (it is namespaced by the device it targets) and may include any number of `source` directives, including none at all. It must specify a single `targets:` parameter, indicating which device is being targeted; the device name itself is arbitrary and is referenced in subsequent `firmware` directives. If native source directives are included, they must be compatible with the targeted device.
+
+#### Grammar
+
+```ruby
+hardware 'name', targets: :device do
+  # source directives
+  # import directives
+  # linker directive
+end
+```
+
+#### Examples
+
+```ruby
+hardware 'startup', targets: :lpc1114 do
+  linker 'arm-none-eabi', isa: 'armv6', cpu: 'cortex-m0' do
+    script 'src/LPC1114.ld'
+    option :nostdlib
+  end
+end
+```
+
+### Firmware Directive
+
+A `firmware` directive must be uniquely named, and takes an `imports` parameter referencing `software` directives by name. It may include any number of `target` directives, enumerating which devices to build the imported software for. A firmware directive becomes a Make target of the same name, which will build the firmware against *all* the specified devices. Additional Make targets of the form `firmware/device` will build it for individual devices.
+
+#### Grammar
+
+```ruby
+firmware 'name', imports: ['software1', 'software2', ...] do
+  # target directives
+end
+```
+
+#### Examples
+
+```ruby
+firmare 'hello_world', imports: ['hello_world_main'] do
+  target :linux_x64 do
+    elf 'bin/hello_world'
+  end
+end
+```
+
+### Linker Directive
+
+Exactly one hardware directive per firmware per device must have a linker directive, which describes how the source code is to be linked together into an executable. The optimization parameter is used for whole-program link time optimization, and can be either a symbol or an integer passed to the linker via `-O`, e.g. `2` for `-O2` or `:fast` for `-Ofast`. Options are passed as-is to the linker, and a linker script can be provided.
+
+#### Grammar
+
+```ruby
+linker 'triple', isa: 'isa', cpu: 'cpu', opt: :opt do
+  # option directives
+  # script directive
+end
+```
+
+#### Example
+
+```ruby
+linker 'arm-none-eabi', isa: 'armv6-m', cpu: 'cortex-m0', opt: :fast do
+  script 'src/cortex-m0.ld'
+  option :nostdlib
+end
+```
+
+### Target Directive
+
+A `target` directive takes a single device name as a parameter, and includes any number of output directives such as `elf` or `bin`. These directives control whether to generate a given build artifact, and where to place it.
+
+The following output directives are available:
+
+ - `elf`: links the software for the device into an ELF file
+ - `bin`: runs the ELF file through `objcopy -O binary`
+ - `hex`: runs the ELF file through `objcopy -O ihex`
+ - `map`: generates a map file while linking
+
+#### Grammar
+
+```ruby
+target :device do
+  # elf directive
+  # bin directive
+  # hex directive
+  # map directive
+end
+```
+
+#### Examples
+
+```ruby
+target :cortex_m4 do
+  elf 'bin/program.elf'
+  map 'bin/program_layout.map'
+end
+```
+
+### Source Directive
+
+A source directive represents a collection of source files of the same language and configuration. All parameters and nested directives depend on the language selected, which the exception of `language:` which specifies said language.
+
+```ruby
+source language: :language, ... do
+  # language-specific directives
+end
+```
+
+### Native Source Directive
+
+Native source directives have no options besides importing files. The source files provided will be passed directly to the linker, in the order given, with no processing performed on them. They can be whatever format the linker understands, such as assembly files or object files for the correct architecture.
+
+#### Grammar
+
+```ruby
+source language: :native do
+  # import directives
+end
+```
+
+#### Examples
+
+```ruby
+source language: :native do
+  import 'src/main.S'
+  import 'lib/startup-armv6.o'
+end
+```
+
+### C Source Directive
+
+C source directives take an array of header include paths as a parameter, and accept source file import directives, option directives (to pass in compiler flags) and define directives (to pass in preprocessor macros).
+
+#### Grammar
+
+```ruby
+source language: :c, headers: ['dir1', 'dir2', ...] do
+  # import directives
+  # option directives
+  # define directives
+end
+```
+
+#### Examples
+
+```ruby
+source language: :c do
+  import 'src/main.c'
+  option :ffreestanding
+  define :NDEBUG
+  define :_POSIX_C_SOURCE => '200809L'
+end
+```
+
+Advanced Usage
+--------------
+
+### Mixins and Ruby Procs
+
+You can use Ruby procs together with the `inject` shorthand, which will effectively run your proc in the context of a directive, like so:
+
+```ruby
+cflags = proc do
+  option :myflag => 'myvalue'
+end
+
+# later...
+
+source language: :c do
+  inject &cflags
+end
+```
+
+### Using Ruby in the build file
+
+The build file is otherwise ordinary Ruby code extended with a custom DSL, therefore you can write any Ruby code inside it, although it is encouraged to keep the build file free of undocumented dependencies such as gems or external commands. For instance, you can do this:
+
+```ruby
+source language: :c, headers: 'include' do
+  define :VERSION => quote(`git rev-parse HEAD`)
+end
+```
+
+### Hardware Abstraction Layers
+
+Because hardware directive names are namespaced by the device they target, HALs are supported by default, as shown below. When built for a given device, this `hal` software directive will resolve to the appropriate hardware directive for that device, assuming one is present:
+
+```ruby
+software 'module', depends: ['hal'] do
+  # ...
+end
+
+hardware 'hal', targets: :device1 do
+  # ...
+end
+
+hardware 'hal', targets: :device2 do
+  # ...
+end
+```
+
+### Some helper Ruby methods
+
+In the spirit of its DSL, Comet defines some convenience methods to make your build file more expressive.
+
+#### quote
+
+The **quote** method will take a string, strip any surrounding whitespace, and surround the result in double quotes. This is useful for passing strings to the C preprocessor through macros. For instance, `define :FOO => quote('bar')` translates to `-DFOO=\"bar\"` which is equivalent to `#define FOO "bar"`.
+
+License
+-------
+
+This software is released under the MIT license. See the LICENSE file for details.

data/Rakefile

@@ -0,0 +1 @@
+require 'bundler/gem_tasks'

data/bin/comet

@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby
+
+require 'comet'
+require 'slop'
+
+# HACK: until https://github.com/leejarvis/slop/pull/214 is fixed
+ARGV.unshift '-f', 'comet.rb' if !ARGV.empty? && ARGV[0] == '--'
+
+options = Slop.parse suppress_errors: true do |opts|
+  opts.banner = 'Usage: comet [-f PATH] [-s] [make arguments...]'
+  opts.string '-f', 'filename of build file', default: 'comet.rb'
+  opts.bool '-V', 'show all makefile output', default: false
+  opts.bool '-s', 'show produced makefile', default: false
+  opts.on '--version', 'print the tool version' do
+    puts "comet v#{Comet::VERSION}"
+    exit
+  end
+  opts.on '-h', '--help', 'show this help message' do
+    puts opts
+    exit
+  end
+end
+
+generator = Comet::Generator.new(options[:f])
+
+if options[:s]
+  puts generator.makefile.contents
+else
+  generator.makefile.execute options.arguments, verbose: options[:V]
+end

data/comet-build.gemspec

@@ -0,0 +1,26 @@
+lib = File.expand_path '../lib', __FILE__
+$LOAD_PATH.unshift lib unless $LOAD_PATH.include? lib
+require 'comet/version'
+
+Gem::Specification.new do |gem|
+  gem.authors       = ['Thomas Beneteau']
+  gem.email         = ['thomas@bitwise.me']
+  gem.description   = 'The no-nonsense build tool for embedded software'
+  gem.summary       = 'Comet is a fast and simple LLVM-oriented build tool'
+  gem.homepage      = 'https://github.com/TomCrypto/Comet'
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = ['comet']
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = 'comet-build'
+  gem.require_paths = ['lib']
+  gem.version       = Comet::VERSION
+
+  gem.add_development_dependency 'bundler', '~> 1.7'
+  gem.add_development_dependency 'rake', '~> 12.0'
+  gem.add_development_dependency 'rspec'
+  gem.add_development_dependency 'rubocop-rspec'
+
+  gem.add_runtime_dependency 'require_all'
+  gem.add_runtime_dependency 'slop'
+end

data/lib/comet/dsl/bin_output.rb

@@ -0,0 +1,19 @@
+module Comet
+  module DSL
+    class BinOutput
+      def initialize(path)
+        @path = path
+      end
+
+      def to_s
+        'bin output'
+      end
+
+      attr_reader :path
+
+      def validate!
+        raise "#{self} path is invalid" if @path.strip.empty?
+      end
+    end
+  end
+end

data/lib/comet/dsl/c/source.rb

@@ -0,0 +1,57 @@
+module Comet
+  module DSL
+    module C
+      class Source
+        include Comet::DSL::Helpers
+        alias inject instance_exec
+
+        def import(pattern)
+          @imports.push pattern
+        end
+
+        def option(*args, **kwargs)
+          @options.add('', *args, **kwargs)
+        end
+
+        def define(*args, **kwargs)
+          @options.add('D', *args, **kwargs)
+        end
+
+        def initialize(headers:, &block)
+          @headers = headers
+          @imports = []
+          @options = Comet::DSL::Options.new
+
+          instance_exec(&block) if block_given?
+        end
+
+        def to_s
+          'C source'
+        end
+
+        attr_reader :headers
+        attr_reader :imports
+        attr_reader :options
+
+        def language
+          :c
+        end
+
+        def native?
+          false
+        end
+
+        def files
+          @imports.flat_map do |pattern|
+            Dir.glob pattern
+          end.uniq
+        end
+
+        def validate!
+          raise "#{self} references no source files" if @imports.empty?
+          @options.validate!
+        end
+      end
+    end
+  end
+end

data/lib/comet/dsl/cpp/source.rb

@@ -0,0 +1,57 @@
+module Comet
+  module DSL
+    module CPP
+      class Source
+        include Comet::DSL::Helpers
+        alias inject instance_exec
+
+        def import(pattern)
+          @imports.push pattern
+        end
+
+        def option(*args, **kwargs)
+          @options.add('', *args, **kwargs)
+        end
+
+        def define(*args, **kwargs)
+          @options.add('D', *args, **kwargs)
+        end
+
+        def initialize(headers:, &block)
+          @headers = headers
+          @imports = []
+          @options = Comet::DSL::Options.new
+
+          instance_exec(&block) if block_given?
+        end
+
+        def to_s
+          'C++ source'
+        end
+
+        attr_reader :headers
+        attr_reader :imports
+        attr_reader :options
+
+        def language
+          :cpp
+        end
+
+        def native?
+          false
+        end
+
+        def files
+          @imports.flat_map do |pattern|
+            Dir.glob pattern
+          end.uniq
+        end
+
+        def validate!
+          raise "#{self} references no source files" if @imports.empty?
+          @options.validate!
+        end
+      end
+    end
+  end
+end

data/lib/comet/dsl/elf_output.rb

@@ -0,0 +1,19 @@
+module Comet
+  module DSL
+    class ElfOutput
+      def initialize(path)
+        @path = path
+      end
+
+      def to_s
+        'elf output'
+      end
+
+      attr_reader :path
+
+      def validate!
+        raise "#{self} path is invalid" if @path.strip.empty?
+      end
+    end
+  end
+end