Merge pull request #1 from ellemenno/v1.0.0

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,131 @@
-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 replace or 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`)
+    * install the Rake tasks 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
+    (using loomlib.rake v1.0.0)
+
+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,71 @@
+# encoding: utf-8
+
+require File.join(File.dirname(__FILE__), 'lib', 'tasks', 'support')
+include LoomTasks
+
+
+def available_tasks_dir()
+  File.join(File.dirname(__FILE__), 'lib', 'tasks')
+end
+
+def installed_tasks_dir()
+  File.join(Dir.home, '.loom', 'tasks')
+end
+
+
+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 lib/tasks/*.rb #{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