mtbuild 0.0.9 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3ce4ca21ffea4af4267971c9c01d59adfd0e7714
-  data.tar.gz: 5d5f4ca2dca2af2fdfe2826be295bab65889782a
+  metadata.gz: 2396c6643e11dac5f4237283b8008a2197a6f836
+  data.tar.gz: 633bd1821dcaa7e207456763c2b57b648a380078
 SHA512:
-  metadata.gz: 1d2da1d95635f92f69e733d8cd370191d592b88305ed608a7bbc4e74bb531a8872dc474b142f46d579a1034971e565b9379bf072cd3a0da964ba708527f4ddb9
-  data.tar.gz: ab6032db4a20132d3656d1a57c3c334a4038cb9fef1862447ea300145ee91c0aef315bfa3a38f9f9ad45d95a0aee6134ba5b3e7e563672bb0376497126903ddd
+  metadata.gz: ebf955f1536eaa5cb307ef35ae5494aceaeb7352c25f43920a23797cc03acbceac0121c0a8179d059f9c79fead2b4a340133936b994ecb436f9740bcef16f6b3
+  data.tar.gz: 1d9c4e05c3ea9ff8ba8ba60bbc2a64e3cf9186a579e72ca5ecc5b308d0c3330e0855ee336931f420ac360ed6e6c82c0f231043bf850c033eb0c9057f5e4e664d

data/CHANGES.md

@@ -1,5 +1,30 @@
 # Release Notes #
 
+
+## MTBuild 0.1.0 ##
+
+### Changes ###
+
+* MTBuild v0.1.0 is a big, API-breaking change.
+* MTBuild now requires Ruby >= 2.0.0.
+* MTBuild now overrides the rake application name to display "mtbuild" as the
+  application name.
+* MTBuild now offers a '--super-dry-run' command line option to perform a dry
+  run of the build where each command is printed, but not executed.
+* Workspaces can now include other workspaces to inherit their projects and
+  configurations.
+* Default tasks can no longer be added to projects. You can only add default
+  tasks to workspaces. If you need default tasks for a project, simply include
+  a lightweight workspace that exists solely to specify default tasks.
+* The "clobber" task is now gone. MTbuild workspaces now generate a top-level
+  "clean" task that cleans all projects. Additionally, each project provides
+  its own "clean" task for cleaning just one project at a time. The "clean"
+  tasks remove all intermediate files and final output, so they behave like
+  the older Rake "clobber" task.
+* Added the "gpp" toolchains. These are similar to the gcc toolchains, but they
+  invoke g++ instead of gcc.
+
+
 ## MTBuild 0.0.9 ##
 
 ### Changes ###
@@ -8,6 +33,7 @@
 * Fixed bug that prevented library include path specification for gcc-based
   toolchains.
 
+
 ## MTBuild 0.0.8 ##
 
 ### Changes ###

data/LICENSE.md

@@ -1,4 +1,4 @@
-Copyright (c) 2014, Mindtribe Product Engineering, Inc.
+Copyright (c) 2014-2015, Mindtribe Product Engineering, Inc.
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

data/README.md

@@ -45,8 +45,6 @@ application_project :MyApp, File.dirname(__FILE__) do |app|
       linker_script: 'src/LinkerFile-Debug.ld'
     )
 
-    app.add_default_tasks('MyApp:Debug')
-
 end
 ```
 
@@ -70,7 +68,7 @@ The ARM toolchain should use the specified linker flags when linking (```ldflags
 
 The ARM toolchain should use the specified linker script when linking (```linker_script: ...```)
 
-When invoked with no parameters, MTBuild will build the Debug configuration of MyApp by default (```app.add_default_tasks('MyApp:Debug')```)
+When invoked with no parameters, MTBuild will do nothing for this project. When invoked as ```mtbuild 'MyApp:Debug'```, MTBuild will build the ```Debug``` configuration of ```MyApp```.
 
 You can find more project examples here: [MTBuild examples](https://github.com/Mindtribe/MTBuild/tree/master/examples)
 
@@ -135,6 +133,12 @@ MTBuild uses Rake. MTBuild projects and workspaces are defined using mtbuildfile
 
 Building is as simple as invoking ```mtbuild``` in a folder containing a mtbuildfile. Under the hood, MTBuild pulls in the MTBuild infrastructure and then invokes Rake.
 
+##### Command Line Options #####
+
+MTBuild supports the standard Rake command line options. Additionally, it adds the following:
+
+* ```--super-dry-run``` This command performs a dry run; however, unlike the Rake dry run, it actually prints the shell commands that would be executed.
+
 #### Project Hierarchy ####
 
 The MTBuild project hierarchy looks roughly like this:
@@ -179,13 +183,13 @@ An MTBuild workspace contains MTBuild projects and can provide default settings
 
 MTBuild workspaces are optional. It's possible to build an MTBuild project by itself--assuming the project provides all settings required to build & isn't relying on a workspace to provide those.
 
-MTBuild builds only the first workspace it finds. If a workspace includes a project that provides its own workspace, the project's workspace is ignored and the higher-level workspace is used. This allows projects--such as libraries--to be built by themselves or included in other workspaces while allowing the workspace to define toolchain settings.
+MTBuild allows workspaces to be nested. A workspace can include another workspace, allowing the parent to reference the child workspace's projects. When you include a child workspace from within your workspace, you can choose whether or not to pull in the child's default tasks. You can also choose to pull configurations up from the child or push configurations down to the child.
 
 ###### Simple Workspace Example #####
 
-mtbuildfile.rb:
+This defines a workspace that includes the "MyLibrary" and "MyApp" projects. The projects are presumed to be defined in their own mtbuildfiles inside sub-folders called "MyLibrary" and "MyApp".
 
-This defines a workspace that includes the "MyLibrary" and "MyApp" projects. The projects are presumed to be defined in their own mtbuildfiles inside sub-folders called "MyLibrary" and "MyApp":
+mtbuildfile.rb:
 
 ```Ruby
 workspace :AppWithLibrary, File.dirname(__FILE__) do |w|
@@ -196,9 +200,9 @@ end
 
 ###### Project Plus Workspace Example #####
 
-mtbuildfile.rb:
+This defines a workspace that includes the MyLibrary project, which is defined in the same mtbuildfile. When a project is defined in the same mtbuildfile, it does not need to be explicitly added to the workspace (in this particular example, the workspace isn't very useful).
 
-This defines a workspace that includes the MyLibrary project, which is defined in the same mtbuildfile. When a project is defined in the same mtbuildfile, it does not need to be explicitly added to the workspace (in this particular example, the workspace isn't very useful):
+mtbuildfile.rb:
 
 ```Ruby
 workspace :MyWorkspace, File.dirname(__FILE__) do |w|
@@ -216,9 +220,9 @@ end
 
 ###### Project Plus Workspace With Defaults Example #####
 
-mtbuildfile.rb:
+This defines a workspace that includes the MyLibrary project, which is defined in the same mtbuildfile. The workspace provides a default toolchain for the "Debug" configuration. A higher-level workspace would override this with its own defaults.
 
-This defines a workspace that includes the MyLibrary project, which is defined in the same mtbuildfile. The workspace provides a default toolchain for the "Debug" configuration. A higher-level workspace would override this with its own defaults:
+mtbuildfile.rb:
 
 ```Ruby
 workspace :MyLibrary, File.dirname(__FILE__) do |w|
@@ -235,6 +239,19 @@ static_library_project :MyLibrary, File.dirname(__FILE__) do |lib|
 end
 ```
 
+###### Nested Workspace Example #####
+
+This defines a workspace that includes a "MyLibrary" workspace and pulls up a configuration called "Debug" from the "MyLibrary" workspace. This makes the library's "Debug" configuration settings available to the "MyApp" project, allowing "MyApp" to be built with the same toolchain settings as "MyLibrary".
+
+mtbuildfile.rb:
+
+```Ruby
+workspace :AppWithLibrary, File.dirname(__FILE__) do |w|
+  w.add_workspace('MyLibrary', pull_configurations: [:Debug])
+  w.add_project('MyApp')
+end
+```
+
 #### Dependencies ####
 
 Configurations can list dependencies that will be built before the configuration. A configuration's dependencies are specified as a list of Rake tasks. Therefore, these dependencies can refer to other MTBuild projects or any Rake task.
@@ -350,8 +367,23 @@ For ```configuration_block```, you supply a block that takes one parameter. When
 #### add_project ####
 Use ```add_project(project_location)``` inside of a workspace configuration block to add a project that lives inside a subfolder. The ```project_location``` parameter must be a subfolder of the workspace. If the project lives at the same level as the workspace, you should define it in the same mtbuildfile as the workspace. In this case, the project will be implicitly added and you do not need to use ```add_project``` inside the workspace. See the **Project Plus Workspace Example** above for an example of a workspace and project that live at the same folder level.
 
+#### add_workspace ####
+Use ```add_workspace(workspace_location, pull_default_tasks: false, pull_configurations: [], push_configurations: [])``` inside of a workspace configuration block to add a child workspace that lives inside a subfolder. The ```workspace_location``` parameter must be a subfolder of the workspace.
+
+The optional, named parameter, ```pull_default_tasks``` determines whether the parent workspace should pull in the child workspace's default tasks. If this is ```true```, then when ```mtbuild``` is run on the parent workspace with no specified build targets, the child workspace's default targets will be built. If this is ```false```, then only targets that are referenced from the child workspace will be built as needed.
+
+The optional, named parameter ```pull_configurations``` specifies a list of configurations to pull up from the child workspace. Pulling up configurations makes them available to other projects included by the parent workspace.
+
+The optional, named parameter ```push_configurations``` specifies a list of configurations to push down to the child workspace. Pushing down configurations allows you to add to a child workspace's configuration settings. Note that pushing a configuration down to a child cannot be used to create a new configuration for that child. It only lets you add configuration settings to child configurations that already exist. MTBuild ignores pushed configurations that do not exist in the child workspace's projects. Pushing down a configuration is intended to allow a parent workspace to override or add to a child's build settings. This should be used rarely and with caution since it's generally assumed that projects in a child workspace have been tested with the settings provided by that workspace.
+
 #### add_default_tasks ####
-Use ```add_default_tasks(default_tasks)``` inside of a workspace configuration block to add tasks that run when you invoke MTBuild with no arguments. The ```default_tasks``` parameter expects one or more (in an array) Rake tasks. If no default tasks are specified, then invoking MTBuild with no arguments will effectively do nothing.
+Use ```add_default_tasks(default_tasks)``` inside of a workspace configuration block to add tasks that run when you invoke MTBuild with no arguments. The ```default_tasks``` parameter expects one or more (in an array) project task names. The project tasks should be qualified relative to the current workspace. For example, if a workspace includes a project called ```MyApp```, which has a configuration called ```Debug```, you can add this by referring to it as ```MyApp:Debug```. If no default tasks are specified, then invoking MTBuild with no arguments will effectively do nothing.
+
+#### add_default_rake_tasks ####
+Use ```add_default_rake_tasks(default_tasks)``` inside of a workspace configuration block to add tasks that run when you invoke MTBuild with no arguments. The ```default_tasks``` parameter expects one or more (in an array) Rake task names. Unlike ```add_default_tasks()```, this method expects "raw" Rake task names. This lets you specify that MTBuild should run any Rake task by default when building this workspace.
+
+#### MTBuild::Workspace.add_default_tasks ####
+Use the class method ```MTBuild::Workspace.add_default_tasks(default_tasks)``` to add a default task outside of a workspace configuration block. This is useful for letting projects register default tasks in the project's mtbuildfile.rb. Note that the tasks specified in the ```default_tasks``` list must be fully-qualified ```mtbuild``` names that take workspace nesting into account. You should use the project method ```task_for_configuration``` to get the correct task names.
 
 #### set_configuration_defaults ####
 Use ```set_configuration_defaults(configuration_name, defaults_hash)``` inside of a workspace configuration block to add default settings for a configuration. This is how you would select, for instance, a default toolchain for all projects with a specific configuration.
@@ -395,6 +427,13 @@ end
 #### set_output_folder ####
 Use ```set_output_folder(output_folder)``` inside of a workspace configuration block to change the build output folder. By default, this folder is set to "build" underneath the workspace folder. The ```output_folder``` parameter expects the name of a folder relative to the workspace. If the folder does not exist, MTBuild will create it.
 
+### MTBuild::Project ###
+
+This is a base class for projects. You won't typically use it directly, but it provides some useful methods for all project types.
+
+#### task_for_configuration ####
+Use ```task_for_configuration(config_name)``` to get the fully qualified task name for the project configuration called ```config_name```. This is useful for getting fully qualified task names to register as default tasks using ```MTBuild::Workspace.add_default_tasks```
+
 
 ### MTBuild::ApplicationProject ###
 
@@ -536,8 +575,9 @@ All toolchains offer the following optional settings:
 
 * ```:library_paths``` - One or more library paths to search when linking. For example, ```'FancyLibrary/lib'``` or ```['FancyLibrary/lib', 'SuperFancyLibrary/lib']```. Note that the paths should be relative to the project folder.
 
+
 ### MTBuild::ToolchainGcc ###
-Define a GCC toolchain by passing ```:gcc``` as the ```toolchain_name``` when invoking the ```toolchain()``` method.
+Define a gcc toolchain by passing ```:gcc``` as the ```toolchain_name``` when invoking the ```toolchain()``` method.
 
 ##### ToolchainGcc settings #####
 On top of the base Toolchain settings, the ToolchainGcc toolchain offers the following optional settings:
@@ -554,14 +594,28 @@ On top of the base Toolchain settings, the ToolchainGcc toolchain offers the fol
 
 * ```:linker_script``` - A linker script file to be used when linking
 
+
+### MTBuild::ToolchainGpp ###
+Define a g++ toolchain by passing ```:gpp``` as the ```toolchain_name``` when invoking the ```toolchain()``` method.
+
+##### ToolchainGpp settings #####
+The ToolchainGpp toolchain uses the same settings as the ToolchainGcc toolchain.
+
+
 ### MTBuild::ToolchainArmNoneEabiGcc ###
 Define an arm-none-eabi-gcc toolchain by passing ```:arm_none_eabi_gcc``` as the ```toolchain_name``` when invoking the ```toolchain()``` method.
 
 ##### ToolchainArmNoneEabiGcc settings #####
 The ToolchainArmNoneEabiGcc toolchain uses the same settings as the ToolchainGcc toolchain.
 
-### MTBuild::Versioner ###
+### MTBuild::ToolchainArmNoneEabiGpp ###
+Define an arm-none-eabi-g++ toolchain by passing ```:arm_none_eabi_gpp``` as the ```toolchain_name``` when invoking the ```toolchain()``` method.
+
+##### ToolchainArmNoneEabiGpp settings #####
+The ToolchainArmNoneEabiGpp toolchain uses the same settings as the ToolchainGcc toolchain.
 
+
+### MTBuild::Versioner ###
 Define a Versioner with the following DSL method:
 
 ```Ruby

data/bin/mtbuild

@@ -1,5 +1,10 @@
 #!/usr/bin/env ruby
 
+lib_path_expanded = File.expand_path(File.join(File.dirname(__FILE__),'..','lib'))
+if File.directory?(lib_path_expanded)
+  $:.unshift(lib_path_expanded) unless $:.include?(lib_path_expanded)
+end
+
 require 'mtbuild'
 
 Rake.application.run

data/lib/mtbuild.rb

@@ -1,6 +1,6 @@
 module MTBuild
   # The current MTBuild version.
-  VERSION = '0.0.9'
+  VERSION = '0.1.0'
 end
 
 require 'rake'

data/lib/mtbuild/application.rb

@@ -9,8 +9,6 @@ end
 
 module MTBuild
 
-  require 'rake'
-
   # This subclasses the Rake::Application class to override default Rake
   # behaviors with MTBuild-specific behaviors
   class Application < Rake::Application
@@ -32,6 +30,19 @@ module MTBuild
       @rakefiles = DEFAULT_RAKEFILES.dup
     end
 
+    def run
+      standard_exception_handling do
+        init
+        load_rakefile
+        top_level
+      end
+    end
+
+    # Override init to pass mtbuild as the app name
+    def init(app_name='mtbuild')
+      super
+    end
+
     # This modifies Rake's command line options to do MTBuild-specific things
     def standard_rake_options
       # This hijacks the "--version" flag and displays the MTBuild version along
@@ -50,10 +61,17 @@ module MTBuild
           opt
         end
       end
-      # This adds MTBuild-specific options (For future development)
-      # options |= [
-      # ]
-      # sort_options(options)
+      # This adds MTBuild-specific options
+      options |= [
+          ['--super-dry-run',
+           "Do a dry run printing actions, but not executing them.",
+           lambda { |value|
+             Rake.verbose(true)
+             Rake.nowrite(true)
+           }
+          ],
+      ]
+      sort_options(options)
     end
 
   end

data/lib/mtbuild/application_configuration.rb

@@ -18,10 +18,10 @@ module MTBuild
         all_object_folders |= object_folders
       end
 
-      application_binaries, application_files, application_folders = @default_toolchain.create_application_tasks(all_object_files, @project_name)
+      application_binaries, application_files, application_folders = @default_toolchain.create_application_tasks(all_object_files, @parent_project.project_name)
       dependencies = @dependencies+all_object_folders+application_folders+application_files+application_binaries
 
-      desc "Build application '#{@project_name}' with configuration '#{@configuration_name}'"
+      desc "Build application '#{@parent_project.project_name}' with configuration '#{@configuration_name}'"
       new_task = application_task @configuration_name => dependencies do |t|
         puts "built application #{t.name}."
         @tests.each do |test|
@@ -34,12 +34,12 @@ module MTBuild
       end
 
       namespace @configuration_name do
-        OrganizedPackageTask.new("#{@project_name}-#{@configuration_name}", :noversion) do |t|
+        OrganizedPackageTask.new("#{@parent_project.project_name}-#{@configuration_name}", :noversion) do |t|
           t.need_tar_gz = true
           t.add_files_to_folder("", application_binaries+application_files)
         end
       end
-      Rake::Task[:"#{@project_name}:#{@configuration_name}:package"].prerequisites.insert(0, :"#{@project_name}:#{@configuration_name}")
+      Rake::Task[:"#{@parent_project.project_name}:#{@configuration_name}:package"].prerequisites.insert(0, :"#{@parent_project.project_name}:#{@configuration_name}")
 
     end
 

data/lib/mtbuild/application_project.rb

@@ -9,11 +9,12 @@ module MTBuild
     # Adds a named ApplicationConfiguration to the project.
     def add_configuration(configuration_name, configuration)
       super
-      default_configuration = Workspace.configuration_defaults.fetch(configuration_name, {})
+      default_configuration = {}
+      default_configuration = @parent_workspace.configuration_defaults.fetch(configuration_name, {}) unless @parent_workspace.nil?
       merged_configuration = Utils.merge_configurations(default_configuration, configuration)
-      cfg = ApplicationConfiguration.new(@project_name, @project_folder, effective_output_folder, configuration_name, merged_configuration)
+      cfg = ApplicationConfiguration.new(self, effective_output_folder, configuration_name, merged_configuration)
       @configurations << cfg
-      return cfg
+      cfg
     end
 
   end

data/lib/mtbuild/build_registry.rb

@@ -0,0 +1,104 @@
+module MTBuild
+
+  # This class holds the mtbuild workspace hierarchy
+  class BuildRegistry
+
+    @workspaces = {}
+    @projects = {}
+    @top_workspace = nil
+    @active_workspace = nil
+
+    @expecting=:project_or_workspace
+
+    class << self
+
+      # The map of registered workspaces
+      attr_reader :workspaces
+
+      # The map of registered projects
+      attr_reader :projects
+
+      # The top-level workspace
+      attr_reader :top_workspace
+
+      # The top-level workspace
+      attr_reader :active_workspace
+
+      # Track the beginning of a new workspace's creation
+      def enter_workspace(workspace_name, workspace)
+        workspace_name = self.hierarchical_name(workspace_name)
+        self.found_workspace(workspace_name)
+        fail "A workspace named #{workspace_name} was already added." if @workspaces.has_key?(workspace_name)
+        @workspaces[workspace_name] = workspace
+        @top_workspace = workspace if @top_workspace.nil?
+        parent = @active_workspace
+        @active_workspace = workspace
+        return workspace_name, parent
+      end
+
+      # Track the re-entry into a parent workspace after importing a child workspace.
+      def reenter_workspace(workspace)
+        last_workspace = @active_workspace
+        @active_workspace = workspace
+        last_workspace
+      end
+
+      # Track the completion of a new workspace's creation
+      def exit_workspace
+      end
+
+      # Track the beginning of a new project's creation
+      def enter_project(project_name, project)
+        project_name = self.hierarchical_name(project_name)
+        self.found_project(project_name)
+        fail "A project named #{project_name} was already added." if @projects.has_key?(project_name)
+        @projects[project_name] = project
+        return project_name, @active_workspace
+      end
+
+      # Track the completion of a new project's creation
+      def exit_project
+      end
+
+      # Register that we next expect to encounter a workspace, not a project
+      def expect_workspace
+        # We expect an explicitly-added workspace.
+        @expecting=:added_workspace
+      end
+
+      # Register that we next expect to encounter a project, not a workspace
+      def expect_project
+        # We expect an explicitly-added project.
+        @expecting=:added_project
+      end
+
+      # Register that we encountered a workspace and verify that it's allowed
+      def found_workspace(workspace_name)
+        unless [:project_or_workspace, :added_workspace].include? @expecting
+          fail "#{workspace_name} was added with add_project(), but it contains a workspace. Use add_workspace() if you want to include it." if @expecting==:added_project
+          fail "Encountered workspace #{workspace_name} declared after a project or another workspace in the same file. This isn't allowed."
+        end
+        # We expect nothing but top-level projects now.
+        @expecting=:project
+      end
+
+      # Register that we encountered a project and verify that it's allowed
+      def found_project(project_name)
+        unless [:project_or_workspace, :project, :added_project].include? @expecting
+          fail "#{project_name} was added with add_workspace(), but it contains a project. Use add_project() if you want to include it." if @expecting==:added_workspace
+        end
+        # We expect nothing but top-level projects now.
+        @expecting=:project
+      end
+
+      # Get a workspace/project name that reflects the workspace/project hierarchy
+      def hierarchical_name(name)
+        return name if @active_workspace.nil?
+        "#{@active_workspace.workspace_name}:#{name}"
+      end
+
+    end
+
+  end
+
+end