flak 0.0.4 → 0.0.5

data/.gitignore

@@ -5,3 +5,4 @@ pkg/*
 .DS_Store
 *.bak
 *~
+doc/

data/.yardoc/checksums

@@ -0,0 +1,28 @@
+lib/flak.rb d340bce937784bfcd1bbebaa86084ae5af9e4a82
+lib/flak/version.rb cd35ff13292bbc0b507250bda64b36af61a34f36
+lib/flak/rake/os.rb c1b4e0d66a5df3aab590d76d5d1f37e04dd451c9
+lib/flak/thor/cli.rb 115ee363faf9e37032ad28b120b2a7de1b9f1cc1
+lib/core_ext/hash.rb 69000f54daaf5590e0fe27696f30b5051abc75a5
+lib/core_ext/string.rb ce6123f37433d42be751c7b895443fc9d3412306
+lib/flak/rake/errors.rb a81eac06edd339276a6344113217707397950b28
+lib/flak/rake/target.rb 5a70fca1d138833a04df547b25d1682e5bf153f8
+lib/flak/thor/wizard.rb e589e54f76cc30978f2a7c03473183c3a695ab78
+lib/flak/thor/generate.rb 1f8b452affe5f270ca474dff8d5c66e0adc531d3
+lib/flak/thor/junk/junk.rb 6d43a2ccff7db42f8d80ad5263e1cf91d2529e13
+lib/flak/thor/target_file.rb 8a14d2e995a777cc4c804d5f34511691c6228f6f
+lib/flak/rake/templates/gl.rb 195545312f846f906d84965add0856743333aa42
+lib/flak/rake/file_actions.rb 0b835790852a16980adcc730de316932e3407c20
+lib/flak/rake/templates/doc.rb 247ec85c88ad00c6ce65a709c50ecd531bd2ca5f
+lib/flak/rake/templates/max.rb 0a1a606e96f44e2d77b28d439fb22383c5bf89ff
+lib/flak/rake/templates/cpp.rb e7a585e4774075740ede90acbddb207035b0f255
+lib/flak/rake/templates/mac.rb 9e0262c50746c575f436d824a0aeffef5284b368
+lib/flak/rake/templates/nuke.rb eb3c7ed047f680930c64a5a24270b2942c0876d4
+lib/flak/rake/templates/maya.rb 6b3794c7521ede7686eab7866c1c3e93e648233e
+lib/flak/rake/templates/shell.rb 925ac7938e986df41646bc6e7c7bffa9a6c1e3c4
+lib/flak/rake/templates/delight.rb 1d2008e31c0ade49239d2022dae7133753648453
+lib/flak/rake/templates/release.rb bd166e288fe560cad03ced6c5ac862612674695d
+lib/flak/rake/templates/maya_app.rb e96e311747592e15876c421a44f5013a629fa072
+lib/flak/rake/templates/environment.rb 5de9a3a893f3f00491fb12a21b0885c345e658c7
+lib/flak/rake/templates/maya_plugin.rb a9ce2b456c0875ec24403d5be8cf0dd40ce3db9c
+lib/flak/rake/templates/merge_engine.rb fb92c7aaf30979f2bbbfee0ef18e72ff187ad527
+lib/flak/thor/templates/doc/lib/helpers.rb 39ae8b890fc96a8221edb0d1a5d6a784ac28403c

data/.yardopts

@@ -0,0 +1 @@
+- Architecture.md MayaModules.md Documenting.md

data/Architecture.md

@@ -0,0 +1,152 @@
+Flak Architecture
+======
+
+
+##Targets##
+
+When you type rake, the Rakefile is executed. It builds {Flak::Target} objects, one for the project, and one for each tool. The process is started by reading the contents of project.yml and any tool.yml file it finds. There is a project.yml at the project root and a tool.yml at the root of each tool. We call these files target files. 
+
+
+<img src= ../target.jpg />
+
+* The name of a target yml file is either tool.yml or project.yml. It is used to build a Target object.
+* A Target extends itself with settings, methods, and tasks from templates specified in the target yml file.
+* Each template is a ruby module that reads a yml file.
+* Template order is important, as settings are merged in such a way that new values override old values.
+* The Environment template is implicitly read first and does not appear in the template list.
+* The target yml file is read again at the end to specify file-lists and to allow the opportunity to override any other settings.
+* The Target makes 2 passes over the templates so that all settings are resolved before any tasks are generated.
+
+
+
+##Templates##
+
+A Target can be thought of as a task builder that inherits functionality from a set of objects that we call templates. If you look in a target file such as tool.yml you'll see a templates section.
+
+    templates:
+    - cpp
+    - maya
+    - maya_plugin
+    - gl
+
+This specifies that a Target will be built and will be extended with settings and methods for writing a c++ maya plugin with openGL. 
+
+The environment template is read implicitly by the Target before any other templates.
+
+The order of templates in a target file is important. Later templates override earlier ones. If for example the `cpp` template specifies that the extension for shared libraries under windows is dll and the `maya_plugin` template specifies mll, then mll will be used because `maya_plugin` is listed after `cpp`.
+
+When a Target specifies a template, it means three things:
+
+1. The target's settings hash is infused with the values from the settings specified in the template
+2. Instance methods defined in the template become instance methods of the target object.
+3. Rake tasks defined in the template are added to the list tasks that can be run on the command line by rake.
+
+##How the Settings Hash is built##
+
+When a Target is created the first step is to build the settings Hash. Here's the process:
+
+* Get the OS and configuration keys from environment.yml
+* Get the list of templates from the target file. e.g tool.yml
+* For each template:
+ * Replace any environment variables found in the pattern: `${ENV_VAR_NAME}`
+ * Flatten the hash based on the os and configuration settings. In other words, if a key is nested in `configuration_something`, or `os_something`, only use it if the somethings in question are the current configuration and current os respectively.
+ * Merge this Hash into the target's settings Hash, overwriting any string values with the new value, and merging any array values.
+* Finally read the target file itself, again, flattening out the OS and configuration, and merging it into the target's settings hash.
+* Expand all FileList globs in the settings hash.
+
+This resolved Hash is what you see when you type 
+
+    rake <target_name>:inspect
+
+Some settings keys are required for building other settings - for example `:product_revision` is required to build some path settings. If these are not present or are the wrong type, then rake tasks will not be generated and you will see a bright red error. In this case not even the rake inspect tasks will be available to help you track down the error. The error does however show the key name and the file it was raised in. 
+
+    settings[:product_revision] is not a String. It is a NilClass. (environment.rb)
+
+Other keys are not required until build time - for example `:include_flag` is used when rake tasks are run, in this case during compilation. If it is missing you will still get a red error, but you will also be able to run `rake -T` to view the entire settings hash. You might see there is a typo such as `:includ_flag`
+
+##Methods##
+
+A Target object also inherits instance methods from the templates it extends. These instance methods provide functionality to the tasks that could not be provided by settings values alone. An example is building a C compile command. As these extended instance methods are only used by tasks when they are run, all the settings will be in place and therefore these methods have access to the `@settings` instance variable.
+
+##Tasks##
+
+Tasks are the things that actually build the product. There are rake tasks for compiling 3delight shaders, c++ applications and DSOs, converting images, copying files, compressing files and even building documentation. In flak, we generate Rake tasks in the `task_factory` method of each template module. Rake tasks may be generated dynamically which considerably reduces the amount of work needed to add file dependencies to a project. Unlike Make, Rake is a Ruby DSL so you get the power of a first class programming language as opposed to the arcane squiggles of Make that have no application anywhere else. See {http://rake.rubyforge.org/files/doc/rational_rdoc.html Rake rationale} or {http://martinfowler.com/articles/rake.html Martin Fowler's Rake page} 
+
+
+The tasks for copying files or processing with erb allow you to add your own rules. You simply specify the source files in a file list under a special key and specify a destination directory with an associated destination key.
+
+###Copy Tasks###
+
+For example if you wanted to add some some shake files to the source and release them to a shake directory at build time, you could do the following.
+
+In the tool.yml file specify the following file lists and put some files in those directories:
+
+    shake_script_copy_files:
+    - shake/*
+    - shake/init/*
+
+The fact that the key ends in `copy_files` is a signal to flak that these files should be copied. It will look for a matching key called `shake_script_destination`, so tool.yml should also contain
+
+    shake_script_destination: 'shake/scripts'
+
+This will create rake tasks for files in the specified shake source directories to be copied to the relative destination when you type rake. Possibly, `~/tools/flintstone/0.0.3/shake/scripts`. 
+
+NOTE: Like many tasks generated by flak, these tasks are not named tasks, so they don't appear when you type `rake -T`. To display all tasks type `rake -P`. These tasks can still be executed individually.
+
+###Erb Tasks###
+
+Erb tasks are similar to copy tasks, the difference being that erb tokens in the file are replaced with the values from the settings hash at build time. 
+
+Suppose you wanted to add a file containing meta information about your product and provide it with the release. 
+
+In the project.yml (the project level target file) file you might specify the following file lists and destination:
+
+    metafile_erb_files:
+    - script/meta.yml.erb
+    metafile_destination: ''
+
+The .erb extension is optional. If it is found it will be stripped away in the destination. 
+
+A key ending in `erb_files` signals that before moving to the destination, its files should be filtered with erb in the context of the target. In other words, you can enter ruby code to be evaluated at build time and it will have access to the settings hash owned by the target. The contents of the file might look like this:
+
+    ---
+    date:                      '<%= Time.now.strftime("%d %B %Y") %>'
+    product_title:             '<%= @settings[:product_name] %>'
+    version_number:            '<%= @settings[:product_revision] %>'
+    owner:                	   '<%= @settings[:author_name] %>'
+
+When you run `rake` the file meta.yml will appear at the root of the release and will contain something like:
+
+    ---
+    date:                      '10 March 2012'
+    product_title:             'flintstone'
+    version_number:            '0.0.1'
+    owner:                	   'Julian Mann'
+
+Admittedly, owner and title are unlikely to change much, so you could type them explicitly. However using values from the settings hash where possible helps to eliminate mistakes and keeps the project <a href="http://en.wikipedia.org/wiki/Don't_repeat_yourself">DRY</a>. See the <a href="ruby-doc.org/stdlib-1.9.3/libdoc/erb/rdoc/ERB.html">ERB Docs</a> for more info on ERB syntax.
+
+###Maya Icon Tasks###
+
+If you simply want to copy image icons to the destination you could use the formula above for copy tasks. However, Maya node icons should be released in a specific format and sometimes at a specific size. Node icons for example should have 2 versions, one 20X20 with the prefix `out_` for the outliner, and one 32x32 with no prefix for the dependency graph. They should both have the extension `xpm`. If you make your icons in photoshop, the ideal workflow is simply to save one image at any size, in any format, and have the different versions created for the outliner and dependency graph when you build the project. This is exactly what flak does. 
+
+In the tool.yml for a maya tool you'll see the keys:
+
+    maya_node_icon_files:
+    - maya/icons/node/*
+    maya_icon_files:
+    - maya/icons/*.jpg
+    maya_icon_copy_files:
+    - maya/icons/*.png
+    - maya/icons/*.xbm
+
+Files specified under `maya_node_icon_files` are converted to 2 versions as detailed above.
+Files specified under `maya_icon_files` are left the same size, but converted to xpm.
+Files specified under `maya_icon_copy_files` are copied using the copy rules above.
+
+You must have image_magick installed for image conversions to work. To see if it is installed type:
+
+    convert
+
+
+
+

data/Documenting.md

@@ -0,0 +1,2 @@
+Documenting Flak Projects
+======

data/MayaModules.md

@@ -0,0 +1,2 @@
+Maya Module Installation
+======

data/README.md

@@ -0,0 +1,173 @@
+
+
+Flak
+======
+
+Description
+--------
+
+Flak is a framework to help you write VFX tools.
+
+You will find flak especially useful if you write tools for Maya but it also helps you write shell scripts, Nuke tools, 3delight shaders and more. 
+
+
+With flak, you create a project which contains any number of tools. Flak projects use Rake (Ruby Make), and as such, one set of configuration files work across all platforms. No need to fire up Visual Studio on Windows or xcode on Mac.
+
+Flak also encourages good documentation by setting up a website skeleton based on [nanoc](http://http://nanoc.stoneship.org/) There are templates for most pages you will need for a software project, so you can concentrate on content and let flak handle presentation at compile time. In addition there are Maya tools to automatically generate flak documentation pages for plugin nodes, commands and scripts.
+
+Install Flak
+--------
+
+Update rubyGems:
+
+	$ sudo gem update --system
+
+Install flak
+
+    $ sudo gem install flak
+
+Usage
+--------
+
+Flak currently has the task: generate, which has two subcommands: project and tool.
+
+Tasks:
+
+    flak generate help [COMMAND]  # Describe subcommands or one specific subcommand
+    flak generate project [name]  # Create a project
+    flak generate tool [name]     # Create a tool
+
+Tasks and subcommands have a single letter alias. Use g for generate, p for project, t for tool.
+
+Create a project
+--------
+
+For this guide we'll create a project called flintstone containing 2 tools, a maya plugin called fred and a compiled shell command called wilma. Generate a project with the following command.
+
+    flak generate project flintstone
+
+or
+
+    flak g p flintstone
+
+It will ask a few questions about the kind of module you want to make. This is so that the relevant paths can be set when the module is installed. Answer yes to all questions for now.
+
+cd into flintstone, fire up your favorite editor and have a look at what was created.
+
+* project.yml - Contains settings related to the project, but not including any of the tools it will contain. 
+* Rakefile.rb - You never need to touch this.
+* build/ - products will be built here before being released
+* config/ - configuration files for different types of build
+* script/ - project related set-up scripts
+* doc/ - documentation
+
+We'll look at the contents of the config directory and project.yml in more depth later. For now, open config/environment.yml and enter your full name in the author field.
+
+As mentioned, Rake is the tool that will build your project. Some project related tasks are available even though the project contains no tools yet. Type rake -T to see a list of named rake tasks.
+
+    rake FlintstoneProject:inspect             # See resolved configuration settings for FlintstoneProject
+    rake FlintstoneProject:release             # Release FlintstoneProject
+    rake build                                 # Build everything
+    rake clean                                 # Remove any temporary products.
+    rake clobber                               # Remove any generated file.
+    rake doc                                   # Release documentation
+    rake doc:tar                               # Build and tar up documentation to tar.gz.
+    rake tar                                   # Build and tar up product to tar.gz.
+
+To see the full hash of project settings, type:  
+
+    rake FlintstoneProject:inspect
+
+These settings are resolved for the configuration and operating system you are using.
+
+To build the project type:
+
+    rake
+
+There should now be the folder  ~/tools/flintstone/0.0.1-darwin with bin and maya subdirectories. There's an install script and some other stuff that will become clear later. 
+
+Back in the flintstone shell, type:
+
+    rake tar
+
+It will tar up the project in your tools folder ready to be deployed to another site.
+
+Now type:
+
+    rake doc
+
+You'll see a website has been made in ~/tools/flintstone/0.0.1-doc The source files for this website are in the project's doc directory in the textile markup format. The templates are designed to allow you to concentrate on writing content without worrying about presentation. When you want to tar up the documentation site, type:
+
+    rake doc:tar
+
+Create tools
+--------
+
+Now generate some tools. Make sure you are in the flintstone directory and enter: 
+
+    flak generate tool fred
+
+Enter "y" for maya plugin. A tool can have at most one compiled target, which is given the name specified in the "name" field in the file tool.yml. It can however have any number of supporting scripts, icons or other resources. Its also fine to have no compiled tools and only create scripts. If that's the case, you can edit config/environment.yml and change agnostic to true. 
+
+As fred is a maya plugin, it will automatically create maya scripts directories. It will also ask if the tool will contain nuke and shell scripts, and if so it will create directories to hold those scripts. Answer "y" for now, just to see what happens. When done, you'll see many new files, including cpp and headers in the src directory.
+
+Now generate the tool wilma, but this time say no to maya plugin and other options until you are asked if it will be a standalone app. enter y.
+
+    flak g t wilma
+
+At this point, you have a skeleton project set up with tools. Now build it again by typing:
+
+    rake
+
+At this stage you may find the compilation fails. If so, check the output in the shell. Maybe paths to compilers are wrong. You can fix these and other settings in config/cpp.yml, config/maya.yml, config/maya_plugin.yml etc.
+
+NOTE: When you type rake with no arguments, you are in fact running the default rake task, which is to release all tools, but no documentation.
+
+You may also notice that since you made the fred and wilma tools there are more rake tasks available when you type:
+
+    rake -T
+
+If there was a problem building Wilma, you may be able to track it down by checking settings for Wilma:
+
+    rake Wilma:inspect  
+
+When the build succeeds, you will find there is now a standalone tool ~/tools/flintstone/0.0.1-darwin/bin/Wilma and a maya plugin ~/tools/flintstone/0.0.1-darwin/maya/plug-ins/Fred with a platform dependent extension: (.bundle on mac, .so on linux, .mll or windows). Of course, these compiled tools don't do anything and the plugin won't load, but at least you have a build process working. If you make a change to one of the source files, wilma.h for example, and type `rake` again you will see that only Wilma gets rebuilt.
+
+Install your module
+--------
+
+####Mac or Linux####
+
+On Mac or Linux, you can now install the module in your environment by running the install script: 
+
+    ~/tools/flintstone/0.0.1-darwin/bin/INSTALL_FLINTSTONE
+
+The purpose of this script is to set up your environment. 
+
+As flintstone is a Maya module, the file in $MAYA_APP_DIR/$MAYA_VERSION/modules/flintstone will be written and will contain the following line:
+
+    + flintstone 0.0.1 /Users/julian/tools/flintstone/0.0.1-darwin/maya
+
+which specifies the path to the module. On startup, Maya appends the suffixes “plug-ins”, “presets”, “scripts”, and “icons”, to this path, and then adds the appended path to `MAYA_PLUG_IN_PATH`, `MAYA_PRESET_PATH`, `MAYA_SCRIPT_PATH`, and `XBMLANGPATH`, respectively. Read more about Maya modules [here](http://download.autodesk.com/us/maya/2010help/index.html?url=Environment_Variables_File_path_variables.htm,topicNumber=d0e676929)
+
+In addition to the maya module setup, Flak also creates a file that appends some locations in the flintstone module to the system path variables and other relevant paths. Have a look in the file: 
+
+~/tools/flintstone/0.0.1-darwin/bin/flintstone.sh
+
+This file is sourced from your .bashrc (have a look), so the variables it contains are available in your shell sessions.
+
+####Windows####
+
+For Windows, the process of installing a released flak module for the user is somewhat more manual. A more automated solution is in progress.
+
+If the module is a Maya module, then make the folder: C:\Users\my_name\Documents\maya\2012-x64\modules and create a plain text document called flintstone. Its important to make sure it has no extension. flintstone.txt for example will NOT work.
+
+Add the following line, 
+
+    flintstone 0.0.1 <path/to/tools>/flintstone/0.0.1-win_64/maya
+
+If the module contains shell scripts, nuke scripts or other files that rely on environment variables, you'll have to append the relevant paths to the system variables. For example:
+
+    FLINTSTONE = <path/to/tools>\flintstone\0.0.1-win_64
+    PATH =   		%PATH%;%FLINTSTONE%\bin
+    NUKE_PATH =   	%NUKE_PATH%;%FLINTSTONE%\nuke\scripts

data/flak.gemspec

@@ -18,12 +18,15 @@ Gem::Specification.new do |s|
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]
 
-  # specify any dependencies here; for example:
-  # s.add_development_dependency "rspec"
   s.add_runtime_dependency "awesome_print"
   s.add_runtime_dependency "nanoc"
-  s.add_runtime_dependency "RedCloth"
   s.add_runtime_dependency "sass"
+  
+  s.add_development_dependency "RedCloth"
+  s.add_development_dependency "yard", "= 0.7.2"
+  s.add_development_dependency "redcarpet"
+  
+  s.has_rdoc = 'yard'
 
 end
 

data/lib/core_ext/hash.rb

@@ -0,0 +1,82 @@
+class Hash
+
+
+  # Turn 'keys' into :symbols
+  def symbolize_keys
+    inject({}) do |options, (key, value)|
+      options[(key.to_sym rescue key) || key] = value
+      options
+    end
+  end
+
+
+  # Merge other into self as a normal merge, with the exception that
+  # when there are duplicate keys and the other.value is an array, 
+  # make a flat uniquified array by merging both arrays together
+  # @param other [Hash] the other Hash
+  # @return [Hash] a new Hash
+  def flak_merge(other)
+    d = self.dup
+    other.each do |k,v|
+      if ( d.has_key?(k)  &&  v.kind_of?(Array) )
+       d[k] = ([ self[k] ] | v.dup ).flatten.uniq
+      else
+        d[k] = v
+      end
+    end
+    d 
+  end
+
+  # Return a value which is an object of value's type.
+  # If key is duplicate in self and value is an array, then merge it
+  # However, if value is not an array, return it, even if self[key] is an array.
+  # We do this to make sure the incoming type takes precedence
+  # same as flak_merge really
+  # @param key [Object] the key
+  # @param value [Object] the value
+  # @return [Object] a new object of the same type as value
+  def flak_merge_key(key,value)
+    if ( self.has_key?(key)  &&  value.kind_of?(Array)    )
+     ([ self[key] ] | value.dup ).flatten.uniq
+    else
+      value
+    end 
+  end
+
+
+  # Looks for keys that are nested under "os_*" or "configuration_*" keys 
+  # or both, i.e. os_* -> configuration_*.
+  # A flattened hash is generated where only agnostic entries, or 
+  #entries for the current os and configration are present.
+  # @param configuration [String] the configuration. e.g.'debug'
+  # @param os [String] the os. e.g.'darwin'
+  def flak_flatten(configuration,os)
+    h = Hash.new
+    self.each do |k,v|
+      if ( ! ((k =~/^os_.*/) || (k =~/^configuration_.*/)) ) 
+        h[k] = h.flak_merge_key(k,v)
+      else
+        if (k == "os_#{os}" )  
+          v.each do |k1,v1|
+            if (k1 =~ /^configuration_.*/ ) 
+              if (k1 == "configuration_#{configuration}" )  
+                v1.each do |k2,v2|
+                  h[k2] = h.flak_merge_key(k2,v2)
+                end
+              end
+            else
+              h[k1] = h.flak_merge_key(k1,v1)
+            end
+          end
+        else
+          if (k == "configuration_#{configuration}" )  
+            v.each do |k1,v1|
+              h[k1] = h.flak_merge_key(k1,v1)
+            end
+          end
+        end
+      end
+    end
+    h.symbolize_keys
+  end
+end