Skip to content

Commit

Permalink
Merge pull request #7 from ellemenno/v3.0.0
Browse files Browse the repository at this point in the history 
v3.0.0
  • Loading branch information
@pixeldroid
pixeldroid authored Nov 22, 2016
2 parents b91e411 + 10972d4 commit 8ff2703
Show file tree
Hide file tree
Showing 20 changed files with 1,090 additions and 588 deletions.
178 changes: 103 additions & 75 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,13 +3,21 @@ loom tasks

Rake tasks for working with loomlibs

- [overview](#overview)
- [installation](#installation)
- [usage](#usage)
- [conventions](#conventions)
- [contributing](#contributing)

<br>

## 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`).
loomlibs are linkable LoomScript code libraries used to expand features of the [Loom SDK][loomsdk].

If you use [Rake][rake] and follow a consistent file layout across projects, these tasks can simplify the steps of seting up, building, installing, testing, demo-ing, and releasing 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.

Expand All @@ -30,75 +38,113 @@ Clone this repo.

0. Scaffold a new project structure:
* `rake -f ~/.loom/tasks/scaffolding.rake new:loomlib`
0. Test and see the auto-created library be built, the test harness and run, and the first test fail:
0. Run `test` to see the auto-created library be built, the test harness run, and the first test fail:
* `rake test`
0. Add your code and tests (in `lib/src/`, and `test/src/`)

### more details

Running `rake` in your project directory will execute the default task, which prints the list of available tasks and some useful info:

Foo v1.2.3 Rakefile running on Ruby 2.3.0 (lib=sprint34, test=sprint34)
rake clean # removes intermediate files to ensure a clean build
rake clobber # removes all generated artifacts to restore project to checkout-like state
rake demo:build # builds FooDemo.loom for sprint34 SDK
rake demo:cli[options] # executes FooDemo.loom as a commandline app, with options
rake demo:gui # launches FooDemo.loom as a GUI app
rake help # show detailed usage and project info
rake lib:build # builds Foo.loomlib for sprint34 SDK
rake lib:install # installs Foo.loomlib into sprint34 SDK
rake lib:release # prepares sdk-specific Foo.loomlib for release, and updates version in README
rake lib:show # lists libs installed for sprint34 SDK
rake lib:uninstall # removes Foo.loomlib from sprint34 SDK
rake set:sdk[id] # sets the provided SDK version into lib/loom.config and test/loom.config
rake set:version[v] # sets the library version number into lib/src/Foo.build and lib/src/pixeldroid/cli/Foo.ls
rake set[sdk] # sets the provided SDK version into lib/loom.config and test/loom.config
rake test # shorthand for rake test:run
rake test:build # builds FooTest.loom against sprint34 SDK
rake test:ci # runs FooTest.loom for CI
rake test:run # runs FooTest.loom for the console
rake version # report loomlib version
(using loomtasks v1.2.1)

use `rake -D` for more detailed task descriptions

If you are looking for more detail on any of the tasks, use `rake -D`, e.g.:

```console
$ rake -D set
rake set[sdk]
sets the provided SDK version into lib/loom.config and test/loom.config
lib/loom.config defines which SDK will be used to compile the loomlib, and also where to install it
test/loom.config defines which SDK will be used to compile the test app and demo app
```
Running `rake` in your project directory will execute the default task, which prints the list of available tasks and a short description of what they do:

Foo v1.2.3 Rakefile running on Ruby 2.3.0
rake clean # removes intermediate files to ensure a clean build
rake cli[options] # shorthand for rake cli:run
rake cli:build # builds cli/bin/FooDemoCLI.loom for sprint34 SDK
rake cli:run[options] # executes cli/bin/FooDemoCLI.loom as a commandline app, with options, if provided
rake cli:sdk[id] # sets the provided SDK version into cli/loom.config
rake clobber # removes all generated artifacts to restore project to checkout-like state
rake gui # shorthand for rake gui:run
rake gui:build # builds gui/bin/FooDemoGUI.loom for sprint34 SDK
rake gui:run # launches gui/bin/FooDemoGUI.loom as a GUI app
rake gui:sdk[id] # sets the provided SDK version into gui/loom.config
rake help # show detailed usage and project info
rake lib:build # builds Foo.loomlib for sprint34 SDK
rake lib:install # installs Foo.loomlib into sprint34 SDK
rake lib:release # prepares sdk-specific Foo.loomlib for release, and updates version in README
rake lib:sdk[id] # sets the provided SDK version into lib/loom.config
rake lib:show # lists libs installed for sprint34 SDK
rake lib:uninstall # removes Foo.loomlib from sprint34 SDK
rake lib:version[v] # sets the library version number into lib/src/Foo.build and lib/src/Foo.ls
rake sdk[id] # sets the provided SDK version in the config files of lib, cli, gui, and test
rake test # shorthand for rake test:run
rake test:build # builds test/bin/FooTest.loom against sprint34 SDK
rake test:ci # runs test/bin/FooTest.loom for CI
rake test:run # runs test/bin/FooTest.loom for the console
rake test:sdk[id] # sets the provided SDK version into test/loom.config
rake version # reports loomlib version
(using loomtasks v3.0.0)

If you are looking for more detail on any of the tasks, use `rake help`.

The Rake tasks are defined with dependencies and modification triggers, so you can just run `rake test` every time you edit a source file, and the library and test app will be rebuilt as needed automatically.


## conventions

The loomlib rake tasks make the following assumptions about the layout of a project:
The loomlib rake tasks make the following assumptions about the layout of a project.

> If there are portions of the scaffold that you are not interested in using (i.e. `cli`, `gui`), just delete those folders, and the corresponding rake tasks will not be loaded.
### directory structure

foo-loomlib $
├─cli/
├─gui/
├─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
* library source is under `lib/`
* source for a CLI demo is under `cli/`; the CLI demo app will consume the library and illustrate its use from the command line
* source for a GUI demo is under `gui/`; the GUI demo app will consume the library and illustrate its use via a graphical user interface
* the project uses a `Rakefile` for building, testing, and preparing releases
* library test source is under `test/`; the test app will consume the library and exercise it
* [spec-ls][spec-ls] is the testing framework

#### demos

Support for CLI demo tasks comes from [`loomlib_cli.rake`](lib/tasks/rakefiles/loomlib_cli.rake).

`cli/` contains a command line demonstration app. <br>

└─cli
├─bin
│ └─Main.loom
├─loom.config
└─src
├─FooDemoCLI.ls
└─FooDemoCLI.build

* the cli demo application is built into, and executed from `cli/bin/`
* the cli demo has its own loom config file at `cli/loom.config`
* the cli demo has its own loom build file at `cli/src/FooDemoCLI.build`
* the cli demo source code is under `cli/src/`

Support for GUI demo tasks comes from [`loomlib_gui.rake`](lib/tasks/rakefiles/loomlib_gui.rake).

`gui/` contains a functional graphical demonstration app. <br>

└─gui
├─assets
├─bin
│ └─Main.loom
├─loom.config
└─src
├─FooDemoGUI.ls
└─FooDemoGUI.build

* the gui demo assets are under `gui/assets/`
* the gui demo application is built into, and run from `gui/bin/`
* the gui demo has its own loom config file at `gui/loom.config`
* the gui demo has its own loom build file at `gui/src/FooDemoGUI.build`
* the gui demo source code is under `gui/src/`

#### lib

`lib/` is for the library code, which will be packaged into a `.loomlib` file for installation into a LoomSDK. <br>
Support for test tasks comes from `loomlib.rake`.
Support for library tasks comes from [`loomlib_lib.rake`](lib/tasks/rakefiles/loomlib_lib.rake).

`lib/` contains the library code, which will be packaged into a `.loomlib` file for installation into a Loom SDK. <br>

├─lib
│ ├─assets
│ ├─bin
│ ├─build
│ │ └─Foo.loomlib
│ ├─loom.config
Expand All @@ -108,30 +154,31 @@ Support for test tasks comes from `loomlib.rake`.
│ └─bar
│ └─Foo.ls

* the loomlib wil be built into `lib/build/`
* the loomlib is 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):
Some file under `lib/` contains the following line (where `1.2.3` is the version of your library):

```ls
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]).
This provides runtime access to the library version, and is also used in the name of the loomlib built for release (compatible with a corresponding [GitHub release][gh-releases]).

#### test

`test/` is for unit tests of the library code. The tests are not packaged with the loomlib; they are run from a separate test runner app. <br>
Support for test tasks comes from `loomlib.rake`. Use of [spec-ls][spec-ls] is assumed.
Support for test tasks comes from [`loomlib_test.rake`](lib/tasks/rakefiles/loomlib_test.rake).
Use of [spec-ls][spec-ls] is assumed.

`test/` contains unit tests of the library code. The tests are not packaged with the loomlib; they are run from a separate test runner app. <br>

└─test
├─assets
├─bin
│ └─FooTest.loom
│ └─Main.loom
├─loom.config
└─src
├─app
Expand All @@ -140,32 +187,12 @@ Support for test tasks comes from `loomlib.rake`. Use of [spec-ls][spec-ls] is a
│ └─FooSpec.ls
└─FooTest.build

* the test application wil be built into `test/bin/`
* the test application is built into, and run from `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/FooTest.build`
* the test application source code is under `test/src/app/`
* the specification source code is under `test/src/spec/`

##### demo

`demo/` is for a functional demonstration app. It may be GUI or commandline. <br>
Support for demo tasks comes from `loomlib_demo.rake`.

└─test
├─assets
├─bin
│ └─FooTest.loom
├─loom.config
└─src
├─demo
│ └─FooDemo.ls
└─FooDemo.build

* the demo application wil be built into `test/bin/`
* the demo shares its loom config file with the test app at `test/loom.config`
* the demo has its own loom build file at `test/src/FooDemo.build`
* the demo source code is under `test/src/demo/`


## contributing

Expand All @@ -174,5 +201,6 @@ Pull requests are welcome!

[gh-releases]: https://help.github.com/articles/about-releases/ "about GitHub releases"
[loomcli]: https://loomsdk.com/#see "See the Loom CLI demo"
[loomsdk]: https://github.com/LoomSDK/LoomSDK "The Loom SDK, a native mobile app and game framework"
[rake]: https://rubygems.org/gems/rake "Rake (Ruby make)"
[spec-ls]: https://github.com/pixeldroid/spec-ls "spec-ls: a simple specification framework for loom"
55 changes: 29 additions & 26 deletions Rakefile
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@

require File.join(File.dirname(__FILE__), 'lib', 'tasks', 'support')
require 'pathname'
require File.join(File.dirname(__FILE__), 'lib', 'tasks', 'rakefiles', 'support')
include LoomTasks


Expand All @@ -11,8 +12,12 @@ def installed_tasks_dir()
File.join(Dir.home, '.loom', 'tasks')
end

def installed_rakefiles_dir()
File.join(installed_tasks_dir, 'rakefiles')
end

def installed_templates_dir()
File.join(Dir.home, '.loom', 'tasks', 'templates')
File.join(installed_tasks_dir, 'templates')
end

task :default => :list_targets
Expand All @@ -22,29 +27,27 @@ task :list_targets do |t, args|
b = "running on Ruby #{RUBY_VERSION}"
puts "#{a} #{b}"
system("rake -T")
puts ''
puts 'use `rake -D` for more detailed task descriptions'
puts ''
end

desc [
"installs rake task files for Loom",
"task files are installed to #{installed_tasks_dir}"
"files will be installed to #{installed_tasks_dir}"
].join("\n")
task :install do |t, args|
Dir.mkdir(installed_tasks_dir) unless Dir.exists?(installed_tasks_dir)
Dir.mkdir(installed_rakefiles_dir) unless Dir.exists?(installed_rakefiles_dir)
Dir.mkdir(installed_templates_dir) unless Dir.exists?(installed_templates_dir)

FileUtils.cp_r(Dir.glob(File.join('lib', 'tasks', '*.rake')), installed_tasks_dir)
FileUtils.cp_r(Dir.glob(File.join('lib', 'tasks', '*.rb')), installed_tasks_dir)
FileUtils.cp_r(Dir.glob(File.join('lib', 'tasks', 'templates', '*.erb')), installed_templates_dir)
FileUtils.cp_r(Dir.glob(File.join('lib', 'tasks', 'rakefiles', '*.rake')), installed_rakefiles_dir)
FileUtils.cp_r(Dir.glob(File.join('lib', 'tasks', 'rakefiles', '*.rb')), installed_rakefiles_dir)
FileUtils.cp_r(Dir.glob(File.join('lib', 'tasks', 'templates', '*')), installed_templates_dir)

puts "[#{t.name}] task completed, tasks installed to #{installed_tasks_dir}"
puts ''
end

desc [
"show usage and project info",
"shows usage and project info",
].join("\n")
task :help do |t, args|
system("rake -D")
Expand All @@ -53,11 +56,10 @@ task :help do |t, args|
puts "Project home page: https://github.com/pixeldroid/loomtasks"
puts ''
puts "Please see the README for additional details."
puts ''
end

desc [
"report loomtasks version",
"reports loomtasks version",
].join("\n")
task :version do |t, args|
puts "loomtasks v#{VERSION}"
Expand All @@ -67,18 +69,19 @@ end
namespace :list do

desc [
"lists task files available to install",
"task files from this project are in #{available_tasks_dir}"
"lists loomtasks files available to install",
"files from this project are in #{available_tasks_dir}"
].join("\n")
task :available do |t, args|
if Dir.exists?(available_tasks_dir)
puts("available tasks in #{available_tasks_dir}")
Dir.glob("#{available_tasks_dir}/*").each { |f| puts(File.basename(f)) }
puts("files available in #{available_tasks_dir}:")
project_root = Pathname.new(available_tasks_dir)
Dir.glob(File.join("#{available_tasks_dir}", '**', '*')).reject { |f| File.directory?(f) }.each do |f|
puts(Pathname.new(f).relative_path_from(project_root).to_s)
end
else
puts "[#{t.name}] no tasks are installed at #{available_tasks_dir}"
puts "[#{t.name}] no files are available at #{available_tasks_dir}"
end

puts ''
end

desc [
Expand All @@ -87,25 +90,25 @@ namespace :list do
].join("\n")
task :installed do |t, args|
if Dir.exists?(installed_tasks_dir)
puts("installed tasks in #{installed_tasks_dir}")
Dir.glob("#{installed_tasks_dir}/*").each { |f| puts(File.basename(f)) }
puts("files installed in #{installed_tasks_dir}:")
project_root = Pathname.new(installed_tasks_dir)
Dir.glob(File.join("#{installed_tasks_dir}", '**', '*')).reject { |f| File.directory?(f) }.each do |f|
puts(Pathname.new(f).relative_path_from(project_root).to_s)
end
else
puts "[#{t.name}] no tasks are installed at #{installed_tasks_dir}"
puts "[#{t.name}] no files are installed at #{installed_tasks_dir}"
end

puts ''
end

end

desc [
"removes the tasks folder from the Loom home directory",
"the task folder is #{installed_tasks_dir}",
"the entire tasks folder is removed, so use with caution if you happened to put anything in there",
"the entire tasks folder will be removed, so use with caution if you happened to put anything in there",
].join("\n")
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
Loading

0 comments on commit 8ff2703

Please sign in to comment.