v1.0.0 release candidate

LICENSE

@@ -1,6 +1,7 @@
 The MIT License (MIT)
 
-Copyright (c) 2014 pixeldroid
+Copyright (c) pixeldroid
+https://github.com/pixeldroid/loomtasks
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,4 +1,130 @@
-loomtasks
-=========
+loom tasks
+==========
 
 Rake tasks for working with loomlibs
+
+
+## overview
+
+If you use [Rake][rake] and follow a consistent file layout across projects, these tasks can provide help for building, testing, releasing and installing loom libraries (`*.loomlib`).
+
+The tasks install into your `.loom` directory, and can be loaded from there into the Rakefiles of your projects.
+They are no substitute for something like Gem or Bundler for Ruby, but they're a first step in that direction.
+
+loom tasks do not interfere with the [loomcli][loomcli]; the two can be used safely together.
+
+
+## conventions
+
+The loomlib rake tasks make the following assumptions about the layout of a project:
+
+### directory structure
+
+ foo-loomlib $
+ ├─lib/
+ ├─Rakefile
+ └─test/
+
+* library source will go under `lib/`
+* the project will use a `Rakefile` for building, testing, and preparing releases
+* library test source will go under `test/`; the test app will consume the library and exercise it
+
+#### lib
+
+ ├─lib
+ │ ├─assets
+ │ ├─bin
+ │ ├─build
+ │ │ └─Foo.loomlib
+ │ ├─loom.config
+ │ └─src
+ │ ├─Foo.build
+ │ └─com
+ │ └─bar
+ │ └─Foo.ls
+
+* the loomlib wil be built into `lib/build/`
+* the library has its own loom config file at `lib/loom.config`
+* the library has its own loom build file at `lib/src/Foo.build`
+* library source code is under `lib/src/`
+
+##### version
+
+Some file under `lib/` must contain the following line (where `1.2.3` is the version of your library):
+
+ public static const version:String = '1.2.3';
+
+This is used to name the loomlib that gets compiled (and anticipates a corresponding [GitHub release][gh-releases]).
+
+#### test
+
+ └─test
+  ├─assets
+  ├─bin
+  │ └─FooTest.loom
+  ├─loom.config
+  └─src
+  ├─app
+  │ └─FooTest.ls
+  ├─spec
+  │ └─FooSpec.ls
+  └─FooTest.build
+
+* the test application wil be built into `test/bin/`
+* the tests have their own loom config file at `test/loom.config`
+* the tests have their own loom build file at `test/src/Foo.build`
+* the test application source code is under `test/src/app/`
+* the specification source code is under `test/src/spec/`
+
+
+## installation
+
+Clone this repo.
+
+0. Run `rake install` to:
+ * create a `tasks` folder in your Loom SDK home directory (`~/.loom`)
+ * put the `.rake` files from this project into it.
+0. Run `rake uninstall` to:
+ * delete the `tasks` folder.
+ * _**Note:** this deletes the whole folder! So be careful if you decide to put your own tasks in there._
+
+
+## usage
+
+In your project's `Rakefile`, declare the name of your library and path to the file containing version info.
+
+ LIB_NAME = 'Foo'
+ LIB_VERSION_FILE = File.join('lib', 'src', 'com', 'bar', 'Foo.ls')
+
+Then load the tasks:
+
+ load(File.join(ENV['HOME'], '.loom', 'tasks', 'loomlib.rake'))
+
+> Note: your whole Rakefile may be just those three lines if there isn't anything else you need to do
+
+Now run `rake` to execute the default task, which will print the list of available tasks and some useful info:
+
+ Foo v1.2.3 Rakefile running on Ruby 2.1.1 (lib=sprint33, test=sprint33)
+ rake clean # Remove any temporary products
+ rake clobber # Remove any generated file
+ rake lib:build # builds Foo.loomlib for the SDK specified in lib/loom.config
+ rake lib:install # installs Foo.loomlib into the SDK specified in lib/loom.config
+ rake lib:release # prepares sdk-specific Foo.loomlib for release
+ rake lib:show # lists libs installed for the SDK specified in lib/loom.config
+ rake lib:uninstall # removes Foo.loomlib from the SDK specified in lib/loom.config
+ rake set[sdk] # sets the provided SDK version into lib/loom.config and test/loom.config
+ rake test:build # builds FooTest.loom with the SDK specified in test/loom.config
+ rake test:ci # runs FooTest.loom for CI
+ rake test:run # runs FooTest.loom
+
+The Rake tasks are defined with dependencies and modification triggers, so you can just run `rake test:run` every time you edit a source file, and the library and test app will be rebuilt as needed automatically.
+
+
+## contributing
+
+Pull requests are welcome!
+
+
+[rake]: https://rubygems.org/gems/rake "Rake (Ruby make)"
+[loomcli]: https://loomsdk.com/#see "See the Loom CLI demo"
+[gh-releases]: https://help.github.com/articles/about-releases/ "about GitHub releases"

Rakefile

@@ -0,0 +1,102 @@
+# encoding: utf-8
+
+require 'etc'
+require 'fileutils'
+require 'json'
+
+@loom_config = nil
+
+
+task :default => :list_targets
+
+task :list_targets do |t, args|
+ a = "#{File.basename(File.dirname(__FILE__))} Rakefile"
+ b = "running on Ruby #{RUBY_VERSION}"
+ puts "#{a} #{b}"
+ system("rake -T")
+ puts ''
+end
+
+desc "installs rake tasks for Loom"
+task :install do |t, args|
+ Dir.mkdir(installed_tasks_dir) unless Dir.exists?(installed_tasks_dir)
+
+ cmd = "cp lib/tasks/*.rake #{installed_tasks_dir}"
+ try(cmd, "failed to install tasks")
+
+ puts "[#{t.name}] task completed, tasks installed to #{installed_tasks_dir}"
+ puts ''
+end
+
+namespace :list do
+
+ desc "lists tasks available to install"
+ task :available do |t, args|
+ if Dir.exists?(available_tasks_dir)
+ cmd = "ls -1 #{available_tasks_dir}/"
+ try(cmd, "failed to list contents of #{available_tasks_dir} directory")
+ else
+ puts "[#{t.name}] no tasks are installed at #{available_tasks_dir}"
+ end
+
+ puts ''
+ end
+
+ desc "lists currently installed tasks"
+ task :installed do |t, args|
+ if Dir.exists?(installed_tasks_dir)
+ cmd = "ls -1 #{installed_tasks_dir}/"
+ try(cmd, "failed to list contents of #{installed_tasks_dir} directory")
+ else
+ puts "[#{t.name}] no tasks are installed at #{installed_tasks_dir}"
+ end
+
+ puts ''
+ end
+
+end
+
+desc "removes the tasks folder from the Loom SDK"
+task :uninstall do |t, args|
+ FileUtils.rm_r(installed_tasks_dir) if Dir.exists?(installed_tasks_dir)
+
+ puts "[#{t.name}] task completed, #{installed_tasks_dir} was removed"
+ puts ''
+end
+
+
+def config()
+ @loom_config || (@loom_config = JSON.parse(File.read(loom_config_file)))
+end
+
+def exec_with_echo(cmd)
+ puts(cmd)
+ stdout = %x[#{cmd}]
+ puts(stdout) unless stdout.empty?
+ $?.exitstatus
+end
+
+def fail(message)
+ abort("◈ #{message}")
+end
+
+def loom_config_file()
+ 'loom.config'
+end
+
+def available_tasks_dir()
+ File.join(File.dirname(__FILE__), 'lib', 'tasks')
+end
+
+def installed_tasks_dir()
+ File.join(Dir.home, '.loom', 'tasks')
+end
+
+def try(cmd, failure_message)
+ fail(failure_message) if (exec_with_echo(cmd) != 0)
+end
+
+def write_loom_config(config)
+ File.open(loom_config_file, 'w') { |f| f.write(JSON.pretty_generate(config)) }
+end
+