Merge pull request #11 from ellemenno/v3.1.0

v3.1.0

README.md

@@ -15,7 +15,7 @@ Rake tasks for working with loomlibs
 
 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 setting up, building, installing, testing, demo-ing, and releasing loom libraries (`*.loomlib`).
+If you use [Rake][rake] and follow a consistent file layout across projects, these tasks can simplify the steps of setting up, building, installing, testing, demo-ing, documenting, and releasing loom libraries (`*.loomlib`).
 
 The tasks install into your `.loom` directory, and can be loaded from there into the Rakefiles of your projects.
 
@@ -47,35 +47,39 @@ Clone this repo.
 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 list_sdks # lists loom sdk versions available use
- 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[seed] # 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.3)
-
-If you are looking for more detail on any of the tasks, use `rake help`.
+ 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:install[b,p] # installs an executable copy of cli/bin/FooDemoCLI.loom on the system
+ 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 cli:uninstall[b,p] # uninstalls the path executable Foo
+ rake clobber # removes all generated artifacts to restore project to checkout-like state
+ rake docs # shorthand for rake docs:ghpages
+ rake docs:ghpages # creates docs ready for rendering by github pages, or jekyll
+ 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 # shows usage and project info, optionally for a specific command
+ 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 list_sdks # lists loom sdk versions available use
+ 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[seed] # 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.1.0)
+
+If you are looking for more detail on any of the tasks, use `rake help`, e.g. `rake help test`.
 
 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.
 
@@ -89,17 +93,38 @@ The loomlib rake tasks make the following assumptions about the layout of a proj
 
  foo-loomlib $
  ├─cli/
+ ├─doc/
  ├─gui/
  ├─lib/
  ├─Rakefile
  └─test/
 
 * 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
+* documentation source is under `doc/`; [lsdoc][lsdoc] is the supported doc generation tool
 * 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
+* [spec-ls][spec-ls] is the supported testing framework
+
+#### documentation
+
+Support for docs tasks comes from [`loomlib_doc.rake`](lib/tasks/rakefiles/loomlib_doc.rake).
+Use of [lsdoc][lsdoc] is assumed.
+
+`doc/` contains source files to be converted into documentation. The documentation is not packaged with the loomlib; it is generated into a `docs/` directory for [GitHub pages][gh-pages] to render. Note that this requires an option be set for the source code repository (see [Publishing from a docs/ folder][gh-docs]).<br>
+
+ └─doc
+  ├─examples/
+  ├─guides/
+  ├─index.md
+  └─lsdoc.config
+
+* (optional) example pages are written under `doc/examples/`; they will have their own tab in the generated docs site
+* (optional) guide pages are written under `doc/examples/`; they will have their own tab in the generated docs site
+* project level configuration for lsdoc is defined in `doc/lsdoc.config`
+* the documentation home page is written in markdown as `doc/index.md`
+* [lsdoc][lsdoc] will use the data under `doc/` to create a site under `docs/` that GitHub Pages will render after it is pushed to your GitHub repository
 
 #### demos
 
@@ -200,7 +225,10 @@ Use of [spec-ls][spec-ls] is assumed.
 Pull requests are welcome!
 
 
-[gh-releases]: https://help.github.com/articles/about-releases/ "about GitHub releases"
+[gh-docs]: https://help.github.com/articles/configuring-a-publishing-source-for-github-pages/#publishing-your-github-pages-site-from-a-docs-folder-on-your-master-branch "publishing your GitHub Pages site from a /docs folder on your master branch"
+[gh-pages]: https://pages.github.com/ "GitHub Pages is a static site hosting service."
+[gh-releases]: https://help.github.com/articles/about-releases/ "releases are GitHub's way of packaging and providing software to your users"
 [loomsdk]: https://github.com/LoomSDK/LoomSDK "The Loom SDK, a native mobile app and game framework"
+[lsdoc]: https://github.com/pixeldroid/lsdoc "generate API documentation from doc comments in LoomScript source code"
 [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"
+[spec-ls]: https://github.com/pixeldroid/spec-ls "a simple specification framework for loom"

Rakefile

@@ -47,23 +47,36 @@ task :install do |t, args|
 end
 
 desc [
- "shows usage and project info",
+ "shows usage and project info, optionally for a specific command",
+ "usage: rake help",
+ " or: rake help <command>",
 ].join("\n")
 task :help do |t, args|
- system("rake -D")
+ # avoid rake errors about undefined tasks; we want to pull args ourselves
+ ARGV.each do |a|
+ task a.to_sym do ; end
+ Rake::Task[a.to_sym].clear
+ end
+
+ cmd = ARGV.fetch(1, nil)
 
- puts "Log bugs to: https://github.com/pixeldroid/loomtasks/issues"
- puts "Project home page: https://github.com/pixeldroid/loomtasks"
- puts ''
- puts "Please see the README for additional details."
+ if (cmd)
+ system("rake -D #{cmd}")
+ else
+ system("rake -D")
+
+ puts "Log bugs to: https://github.com/pixeldroid/loomtasks/issues"
+ puts "Project home page: https://github.com/pixeldroid/loomtasks"
+ puts ''
+ puts "Please see the README for additional details."
+ end
 end
 
 desc [
- "reports loomtasks version",
+ "reports loomtasks version (v#{VERSION})",
 ].join("\n")
 task :version do |t, args|
  puts "loomtasks v#{VERSION}"
- puts ''
 end
 
 namespace :list do
@@ -105,7 +118,7 @@ end
 desc [
  "removes the tasks folder from the Loom home directory",
  "the task folder is #{installed_tasks_dir}",
- "the entire tasks folder will be 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 added anything in there",
 ].join("\n")
 task :uninstall do |t, args|
  FileUtils.rm_r(installed_tasks_dir) if Dir.exists?(installed_tasks_dir)

lib/tasks/loomlib.rake

@@ -80,16 +80,26 @@ task :list_targets => :check_consts do |t, args|
 end
 
 task :check_consts do |t, args|
- fail("please define the LIB_NAME constant before loading #{File.basename(__FILE__)}") unless LoomTasks.const_lib_name
- fail("please define the LIB_VERSION_FILE constant before loading #{File.basename(__FILE__)}") unless LoomTasks.const_lib_version_file
+ LoomTasks.fail("please define the LIB_NAME constant before loading #{File.basename(__FILE__)}") unless LoomTasks.const_lib_name
+ LoomTasks.fail("please define the LIB_VERSION_FILE constant before loading #{File.basename(__FILE__)}") unless LoomTasks.const_lib_version_file
 end
 
 
 desc [
- "show detailed usage and project info",
+ "shows usage and project info, optionally for a specific command",
+ "usage: rake help",
+ " or: rake help <command>",
 ].join("\n")
 task :help do |t, args|
- system('rake -D')
+ # avoid rake errors about undefined tasks; we want to pull args ourselves
+ ARGV.each do |a|
+ task a.to_sym do ; end
+ Rake::Task[a.to_sym].clear
+ end
+
+ cmd = ARGV.fetch(1, nil)
+ system("rake -D #{cmd}") if (cmd)
+ system("rake -D") unless (cmd)
 
  puts "Please see the README for additional details."
 end
@@ -104,7 +114,7 @@ task :sdk, [:id] do |t, args|
  sdk_version = args.id
  lib_dir = LoomTasks.libs_path(sdk_version)
 
- fail("no sdk named '#{sdk_version}' found in #{sdk_root}") unless (Dir.exists?(lib_dir))
+ LoomTasks.fail("no sdk named '#{sdk_version}' found in #{sdk_root}") unless (Dir.exists?(lib_dir))
 
  Rake::Task['lib:sdk'].invoke(sdk_version)
  Rake::Task['cli:sdk'].invoke(sdk_version)

lib/tasks/rakefiles/loomlib_cli.rake

@@ -19,6 +19,20 @@ def write_cli_config(config)
  LoomTasks.write_loom_config(cli_config_file, config)
 end
 
+def cli_wrapper()
+ ext = windows? ? 'bat' : 'sh'
+ File.join('cli', 'wrapper', "#{LoomTasks.const_lib_name}.#{ext}")
+end
+
+def cli_default_path_dir()
+ File.join(Dir.home, 'bin')
+end
+
+def cli_default_bin_dir()
+ File.join(Dir.home, '.loom', LoomTasks.const_lib_name)
+end
+
+
 DEMO_CLI = File.join('cli', 'bin', "#{LoomTasks.const_lib_name}DemoCLI.loom")
 
 [
@@ -33,7 +47,11 @@ file DEMO_CLI => LIBRARY do |t, args|
  compile_demo('cli', "#{LoomTasks.const_lib_name}DemoCLI.build", cli_config)
 end
 
-FileList[File.join('cli', 'src', '**', '*.ls')].each do |src|
+FileList[
+ File.join('cli', 'loom.config'),
+ File.join('cli', 'src', '*.build'),
+ File.join('cli', 'src', '**', '*.ls'),
+].each do |src|
  file DEMO_CLI => src
 end
 
@@ -50,6 +68,51 @@ namespace :cli do
  puts "[#{t.name}] task completed, find .loom in cli/bin/"
  end
 
+ desc [
+ "installs an executable copy of #{DEMO_CLI} on the system",
+ "the binary is renamed 'Main.loom' and stored under #{cli_default_bin_dir}; override with :b",
+ "a wrapper script is installed on the path at #{cli_default_path_dir}; override with :p",
+ ].join("\n")
+ task :install, [:b, :p] => DEMO_CLI do |t, args|
+ args.with_defaults(
+ :b => cli_default_bin_dir,
+ :p => cli_default_path_dir,
+ )
+
+ sdk_version = cli_config['sdk_version']
+ loomexec = LoomTasks.loomexec(sdk_version)
+ binary = t.prerequisites[0]
+
+ cli_bin_dir = args.b
+ cli_path_dir = args.p
+ target_bin = File.join(cli_bin_dir, LoomTasks.main_binary)
+ target_bin_dir = File.dirname(target_bin)
+ target_exe = File.join(cli_bin_dir, LoomTasks.const_lib_name)
+ target_wrapper = File.join(cli_path_dir, LoomTasks.const_lib_name)
+
+ if (Dir.exists?(cli_bin_dir))
+ puts "[#{t.name}] removing existing #{cli_bin_dir}..."
+ FileUtils.rm_r(cli_bin_dir)
+ end
+ puts "[#{t.name}] creating #{target_bin_dir}..."
+ FileUtils.mkdir_p(target_bin_dir) unless Dir.exists?(target_bin_dir)
+
+ puts "[#{t.name}] copying #{binary} into #{target_bin}..."
+ fail("could not find '#{binary}' to copy") unless File.exists?(binary)
+ FileUtils.cp(binary, target_bin)
+
+ puts "[#{t.name}] copying #{loomexec} into #{target_exe}..."
+ fail("could not find '#{loomexec}' to copy") unless File.exists?(loomexec)
+ FileUtils.cp(loomexec, target_exe)
+
+ puts "[#{t.name}] copying #{cli_wrapper} into #{target_wrapper}..."
+ fail("could not find '#{cli_wrapper}' to copy") unless File.exists?(cli_wrapper)
+ FileUtils.cp(cli_wrapper, target_wrapper)
+ FileUtils.chmod('u=wrx,go=rx', target_wrapper) # 755 on wrapper script to be executable for all, editable by user
+
+ puts "[#{t.name}] task completed, #{LoomTasks.const_lib_name} installed for use"
+ end
+
  desc [
  "executes #{DEMO_CLI} as a commandline app, with options, if provided",
  "your demo application class should extend system.application.ConsoleApplication",
@@ -84,14 +147,46 @@ namespace :cli do
  sdk_version = args.id
  lib_dir = LoomTasks.libs_path(sdk_version)
 
- fail("no sdk named '#{sdk_version}' found in #{sdk_root}") unless (Dir.exists?(lib_dir))
+ LoomTasks.fail("no sdk named '#{sdk_version}' found in #{sdk_root}") unless (Dir.exists?(lib_dir))
 
  cli_config['sdk_version'] = sdk_version
  write_cli_config(cli_config)
 
  puts "[#{t.name}] task completed, sdk updated to #{sdk_version}"
  end
 
+ desc [
+ "uninstalls the path executable #{LoomTasks.const_lib_name}",
+ "the executable directory '#{cli_default_bin_dir}' is removed; override with :bin_dir",
+ "the wrapper shell script is removed from #{cli_default_path_dir}; override with :p",
+ ].join("\n")
+ task :uninstall, [:b, :p] do |t, args|
+ args.with_defaults(
+ :b => cli_default_bin_dir,
+ :p => cli_default_path_dir,
+ )
+ sdk_version = lib_config['sdk_version']
+ sdk_dir = LoomTasks.sdk_root(sdk_version)
+
+ cli_bin_dir = args.b
+ cli_path_dir = args.p
+
+ if (Dir.exists?(cli_bin_dir))
+ FileUtils.rm_r(cli_bin_dir)
+ puts "[#{t.name}] task completed, #{cli_bin_dir} removed"
+ else
+ puts "[#{t.name}] nothing to do; no #{cli_bin_dir} found"
+ end
+
+ installed_wrapper = File.join(cli_path_dir, LoomTasks.const_lib_name)
+ if (File.exists?(installed_wrapper))
+ FileUtils.rm_r(installed_wrapper)
+ puts "[#{t.name}] task completed, #{LoomTasks.const_lib_name} removed from #{cli_path_dir}"
+ else
+ puts "[#{t.name}] nothing to do; no #{LoomTasks.const_lib_name} found in #{cli_path_dir}"
+ end
+ end
+
 end
 
 desc [