Tasks Reference

Here is the reference for bee tasks:

Run another bee build file.

• file: the build file to run, relative to current build file. Optional, defaults to ‘build.yml’.
• target: target or list of targets to run (default target if omitted).
• properties: boolean (true or false) that tells if properties of current build file should be sent and overwrite those of target build. Properties modified in child build don’t change in parent one. Defaults to false.

Example

 - bee:
     file:       "doc/build.yml"
     target:     "pdf"
     properties: true

Print contents of a given file on the console. Parameter is the name of the file to output, as a String.

Example

 - cat: "doc/welcome-message.txt"

Change working directory. This change will persist for all tasks in the current target. Entering a new target, working directory will recover its default value, which is the directory of the build file (or property ‘base’). Parameter is a String with directory to change to.

Example

 - cd: "build"

Change permissions for a set of files. Parameters is a Hash with following entries:

• files: files to change permissions for, as a glob.
• mode: permissons as an Unix integer (such as 0644 or 0755). Note that numbers starting with 0 are considered octal, with 0x, they are supposed to be hexa and in base 10 otherwise.
• recursive: tells if should process directories recursively. Optional, defaults to ‘false’.

Example:

  - chmod:
      files: /usr/local/bin/*
      mode:  0755

Note:

  This task is not implemented under Windows.

Change owner and group for a set of files. Parameters is a Hash with following entries:

• files: files to change owner for, as a glob.
• user: the user to change for, may be a name or an ID (integer). If not set, the user is not changed.
• group: the group to change for, may be a name or an ID (integer). If not set, the group is not changed.
• recursive: tells if should process directories recursively. Optional, defaults to ‘false’.

Example:

  - chown:
      files:     /home/casa
      user:      casa
      group:     staff
      recursive: true

Note:

  This task is not implemented under Windows.

Copy filtered files. Parameter is a hash with following entries:

• root: root directory for files to copy. Optional, defaults to current directory.
• includes: list of globs for files to copy. Optional, defaults to ’**/*’ to include all files recursively.
• excludes: list of globs for files to exclude from copy. Optional, default to nil to exclude no file.
• dotmatch: tells if joker matches dot files. Optional, defaults to false.
• flatten: tells if included files should be copied in destination directory, ignoring their subdirectory. Optional, defaults to false.
• dest: destination directory for the copy, must be an existing directory.
• lenient: tells if copy is lenient, which will silently succeed on errors (for instance if root or destination directory don’t exist). Optional, defaults to false.

Example:

To copy all files from directory ‘src’, except those living in ‘CVS’ directories, into directory ‘destination’, you could write:

  - copy:
      root:     src
      includes: **/*
      excludes: **/CVS/**/*
      dest:     destination

Note: this task only deals with files. Thus, ‘includes’ and ‘excludes’ globs should be ones for files.

Copy files or directories to destination file or directory. Parameter is a Hash with following entries:

• src: glob or list of globs for source files or directories to copy. Included source directories are copied recursively.
• dest: destination file or directory.

Example

 - cp:
     src:  "img/*"
     dest: :doc

Print a message on console. If message is not a string, this task outputs the inspected value of the object.

• message: message to print.

Example

 - echo: "Hello World!"

Run an ERB file or source in bee context and store result in a file or property. Parameter is a Hash with following entries:

• source: ERB source text (if no ‘src’).
• src: ERB file name (if no ‘source’).
• dest: file where to store result (if no ‘property’).
• property: property name where to store result (if no ‘dest’).
• options: ERB options, a String containing one or more of the following modifiers: % enables Ruby code processing for lines beginning with % <> omit newline for lines starting with <% and ending in %> > omit newline for lines ending in %>

For more information ebout ERB syntax, please see documentation at: http://www.ruby-doc.org/stdlib/libdoc/erb/rdoc/.

Example

 - erb: { src: "gem.spec.erb", dest: "gem.spec" }

Notes

In these ERB files, you can access a property foo writing:

 <p>Hello <%= foo %>!</p>

Find files for a glob or list of globs and store list in a property. Parameter is a Hash with entries:

• root: root directory for file search. Defaults to ’.’ (current directory).
• includes: glob or list of globs for files to look for. Defaults to ’**/*’ to include all files recursively.
• excludes: glob or list of globs for files to exclude from search. Defaults to nil to exclude no file.
• dotmatch: tells if joker matches dot files. Optional, defaults to false.
• property: name of the property to set.
• join: a character used to join the list in a string. Defaults to nil so that list is not joined.

Example

To find all PNG in files in ‘img’ directory, and store the list in property image_files, one could write:

 - find:
     root:     "img"
     includes: "**/*.png"
     property: "image_files"

For construct iterates on a list in the ‘in’ entry, putting values in a property which name is in the ‘for’ entry and running the block in the ‘do’ entry for each value.

• for: the name of the property which receives values of the iteration, as a string.
• in: a list on which to iterate. This can be a list, a ruby expression to evaluate in the context of the build to obtain the Enumerable on which to iterate or a symbol that refers to a property that is a list.
• do: the block to run at each iteration.

Example

  - for: file
    in:  [foo, bar]
    do:
      - print: "Creating #{file}..."
      - touch: :file

The same using a reference to a property that is a list:

  - properties:
      list: ['foo', 'bar']

  - target: test
    script:
    - for: name
      in:  :list
      do:
      - print: "Hi #{name}!"

To iterate five times, we could write (using a Ruby Range):

  - for: i
    in:  (1..5)
    do:
      - print: :i

To iterate on files in current directory, we could write:

  - for: file
    in:  "Dir.glob('*')"
    do:
      - print: :file

Get a file from a remote FTP site. Raises a build error this operation fails. Parameter is a hash with following entries:

• username: the username to connect to FTP. Defaults to anonymous.
• password: the password to connect to FTP. Defaults to no password.
• host: the hostname to connect to.
• file: the FTP path to remote file to get.
• output: the local path to file to write. Defaults to same file name in current directory.
• binary: sets the binary mode for download. Defaults to true.

Example:

  - ftp_get:
      username: foo
      password: bar
      host: foo
      file: test.txt

Login to a remote FTP site. Useful to test a connection. Raises a build error if connection fails. Parameter is a hash with following entries:

• username: the username to connect to FTP. Defaults to anonymous.
• password: the password to connect to FTP. Defaults to no password.
• host: the hostname to connect to.

Example

  - ftp_login:
      username: foo
      password: bar
      host:     example.com

Make a directory on a remote FTP site. Raises a build error this operation fails. Parameter is a hash with following entries:

• username: the username to connect to FTP. Defaults to anonymous.
• password: the password to connect to FTP. Defaults to no password.
• host: the hostname to connect to.
• dir: the path of the remote directory to create.

Example:

  - ftp_mkdir:
      username: foo
      password: bar
      host: foo
      dir:  test

Put a file to a remote FTP site. Raises a build error this operation fails. Parameter is a hash with following entries:

• username: the username to connect to FTP. Defaults to anonymous.
• password: the password to connect to FTP. Defaults to no password.
• host: the hostname to connect to.
• file: locale file to send.
• tofile: remote file to write on remote server. Defaults to base name of local file.
• binary: sets the binary mode for upload. Defaults to true.

Example:

  - ftp_put:
      username: foo
      password: bar
      host: foo
      file: test.txt

Generate a Gem package in current directory, named after the Gem name and version. Parameter is the name of the Gem description file.

Example

 - gem: :gem_spec

Expand a GZIP archive for a given file. Parameter is a Hash with following entries:

• src: GZIP file to expand.
• dest: destination for expanded file. Destination file can be guessed (and thus omitted) for src files ’.gz’, ’.gzip’ and ’.tgz’; corresponding dest for latest will be ’.tar’.

Example

 - gunzip:
     src: "dist.tar.gz"
     dest: "dist.tar"

Generate a GZIP archive for a given file. Parameter is a Hash with following entries:

• src: source file to generate GZIP for.
• dest: GZIP file to generate. Defaults to the src file with ’.gz’ extension added.

Example

 - gzip:
     src: "dist.tar"
     dest: "dist.tar.gz"

Get a given URL and store its content in a given file. Parameters is a Hash with following entries:

• url: the URL to get.
• dest: destination file. Optional, defaults to retrieved file name in current directory. If destination is a directory, file is saved in destination directory with the name of the retrieved file.
• prop: Property to set with content of the response body. Optional defaults to output in a file.
• limit: the redirections limit. Optional, defaults to 10.
• username: username for HTTP basic authentication. Optional.
• password: password for HTTP basic authentication. Optional.

Example

  - get:
      url: http://rubyforge.org/frs/download.php/22185/bee-0.4.0.zip

If construct will evaluate the expression in the ‘if’ entry and run block in the ‘then’ entry or ‘else’ entry accordingly.

• if: the condition to evaluate. This is a Ruby expression (thus a string) evaluated in the build context, a symbol that refers to a property or a boolean.
• then: block that is evaluated if condition in if is true.
• else: block that is evaluated if condition in if is false.

Example

  - if: RUBY_PLATFORM =~ /darwin/
    then:
    - print: Hello, I'm a Mac
    else:
    - print: Hello, I'm a PC

Alias for ln.

Make a symbolic link from a source file to a destination one. Parameter is a Hash with following entries:

• old: source of the link, as a glob. If there are more than one file to link, this task will make links ‘new/file’ for each file of the glob.
• new: destination of the link.

Example

  - ln:
      old: /usr/local
      new: /opt

Note:

  This task is not implemented under Windows.

Send an email using SMTP.

• from: The sender of the email.
• to: Recipient of the email. This may be a list of recipients.
• subject: The subject of the email.
• message: The body of the email.
• smtp: The address of the SMTP server.
• encoding: The message encoding. Defaults to ASCII.

Example

  - mail:
      from:    "foo@bee.com"
      to:      "bar@bee.com"
      subject: "Bee Release 0.6.2"
      message: "Hi! There is a new Bee release!"
      smtp:    "smtp.bee.com"

Make a directory, and parent directories if necessary. Doesn’t complain if directory already exists. Parameter is directory to create as a String or a list of directories as an Array of Strings.

Example

 - mkdir: "foo/bar"

Move filtered files. Parameter is a hash with following entries:

• root: root directory for files to move. Optional, defaults to current directory.
• includes: list of globs for files to move. Optional, defaults to ’**/*’ to include all files recursively.
• excludes: list of globs for files to exclude from move. Optional, default to nil to exclude no file.
• flatten: tells if included files should be moved to destination directory, ignoring their subdirectory. Optional, defaults to false.
• dotmatch: tells if joker matches dot files. Optional, defaults to false.
• lenient: tells if move is lenient, which will silently succeed on errors (for instance if root or destination directory don’t exist). Optional, defaults to false.

Example:

To move all files from directory ‘src’, except those living in ‘CVS’ directories, into directory ‘destination’, you could write:

  - move:
      root:     src
      includes: **/*
      excludes: **/CVS/**/*
      dest:     destination

Note: this task only deals with files. Thus, ‘includes’ and ‘excludes’ globs should be ones for files and directories from root will not be affected by this task.

Moves files or directories to destination file or directory. Parameter is a Hash with following entries:

• src: glob or list of globs for source files or directories to move. Included source directories are moved recursively.
• dest: destination file or directory.

Example

 - mv:
     src:  "**/*~"
     dest: :trash

Alias for echo.

Prompt the user for the value of a given property matching a pattern.

• message: message to print at prompt. Should include a description of the expected pattern.
• property: the name of the property to set.
• default: default value if user doesn’t type anything. Written into square brakets after prompt message. Optional.
• pattern: a Ruby pattern for prompted value. If this pattern is not matched, this task will prompt again. Optional, if no pattern is given, any value is accepted.
• error: the error message to print when pattern is not matched.
• attempts: number of allowed attempts. Optional, defaults to 0, which means an unlimited number of attempts.
• echo: the character to echo while typing. Useful for passwords, echoing ’*’ for instance.

Example

 - prompt:
     message:  "Enter your age"
     property: "age"
     default:  "18"
     pattern:  "^\\d+$"
     error:    "Age must be a positive integer"

Put working directory in a given property. Parameter is the name of the property to write current directory into.

Example

  - pwd: current_dir

Alias for throw.

Generate RDoc documentation for a given list of globs to include or exclude and a destination directory. Parameter is a Hash with following entries:

• root: root directory for files to include. Defaults to current directory.
• includes: glob or list of globs for files or directories to document. Defaults to ’**/*’ to include all files.
• excludes: glob or list of globs for files or directories that should not be documented. Defaults to nil to exclude no file.
• dotmatch: tells if joker matches dot files. Optional, defaults to false.
• dest: destination directory for generated documentation.
• options: additional options as a string or list of strings.

Example

 - rdoc:
     includes: ["README", "LICENSE", "#{src}/**/*"]
     dest: :api

Tests a required library and prints an error message if import fails. Parameter is a Hash with entries:

• library: required library (as in require call).
• message: error message to print if require fails.

Example

 - required:
     library: foo
     message: >
       Library foo must be installed (gem install foo) to run
       task bar.

Delete files for a given glob or list of globs. Parameter is a glob or list of globs for files to delete. This task will raise an error if told to delete a directory. Use task ‘rmrf’ to do so.

Example

 - rm: ["**/*~", "**/.DS_Store"]

Alias for rmrf.

Delete files and directories recursively. Parameter is a glob or list of globs for files and directories to delete.

Example

 - rmrf: :build

Wait for a given amount of time.

• time: time to wait, in seconds, as an integer or float.

Example

 - sleep: 3.5

Generate a TAR archive. Parameter is a Hash with following entries:

• root: root directory for files to include. Defaults to current directory.
• includes: glob or list of globs for files to select for the archive. Defaults to ’**/*’ to include all files recursively.
• excludes: glob or list of globs for files to exclude from the archive. Defaults to nil to exclude no file.
• dotmatch: tells if joker matches dot files. Optional, defaults to false.
• dest: the archive file to generate.

Example

 - tar:
     includes: "**/*"
     excludes: ["build", "build/**/*", "**/*~"]
     dest: :tar_archive

Note

If archive already exists, it’s overwritten.

Generate a TAR.GZ archive. Parameter is a Hash with following entries:

• root: root directory for files to include. Defaults to current directory.
• includes: glob or list of globs for files to select for the archive. Defaults to ’**/*’ to include all files recursively.
• excludes: glob or list of globs for files to exclude from the archive. Defaults to nil to exclude no file.
• dotmatch: tells if joker matches dot files. Optional, defaults to false.
• dest: the archive file to generate.

Example

 - targz:
     excludes: ["build/**/*", "**/*~"]
     dest:     :targz_archive

Note

If archive already exists, it’s overwritten.

Run Ruby unit tests listed as a glob or list of globs in a given directory (that defaults to current one). Parameter is a Hash with following entries:

• root: root directory for files to include. Defaults to current directory.
• includes: glob or list of globs for unit test files to run. Defaults to ’**/*’ to include all files recursively.
• excludes: glob or list of globs for unit test files to exclude. Defaults to nil to exclude no file.
• dotmatch: tells if joker matches dot files. Optional, defaults to false.
• dir: directory where to run unit tests.

Example

 - find:
     root:     :test
     includes: "**/tc_*.rb"
     dir:      "test"

Notes

For ruby 1.9 and later, you must install gem ‘test-unit’ to run this task.

Throw a build error with a given message.

• message: the error message. Will be printed on the console as the build failure reason.

Example

  - if: "not File.exists?('/etc/config')"
    then:
    - throw: "No /etc/config file found!"

Update modification time and access time of files in a list. Files are created if they don’t exist. Parameter is a glob or list of globs for files to touch.

Example

  - touch: '#{target}/classes/**/*.class'

Try construct will run the block in the ‘try’ entry and will switch to block in the ‘catch’ entry if an error occurs.

• try: the block to run.
• catch: the block to switch to if an error occurs.

Example:

  - try:
    - print: "In the try block"
    - throw: "Something went terribly wrong!"
    catch:
    - print: "An error occured"

Extract TAR archive to a destination directory. Gziped archives are managed if their extension is ’.tgz’ or ’.tar.gz’. Extracted files are overwritten if they already exist. Parameter is a Hash with following entries:

• src: archive to extract.
• dest: destination directory for extracted files. Optional, defaults to current directory.

Example

  - untar:
      src:  myarchive.tar.gz
      dest: mydir

Extract ZIP archive to a destination directory. Existing extracted files are not overwritten and result in an error. Parameter is a Hash with following entries:

• src: archive to extract.
• dest: destination directory for extracted files. Optional, defaults to current directory.

Example

  - unzip:
      src:  myarchive.zip
      dest: mydir

Alias for sleep.

While construct will run the block in the ‘do’ entry while the condition in the ‘while’ entry is true.

• while: the condition to evaluate. This is a Ruby expression evaluated in the build context.
• do: the block to run while the condition is true.

Example:

  - while: i > 0
    do:
    - print: :i
    - rb: i -= 1

Dump the content of a given property into a YAML file.

• prop: the property to dump.
• file: the YAML file name to dump into.

Example

 - yaml_dump:
     prop: "my_list"
     file: "my_list.yml"

Load a YAML file in a given property.

• file: the YAML file name to load.
• prop: the property name to set with YAML parsed content.

Example

 - yaml_load:
     file: "my_list.yml"
     prop: "my_list"

Generate a ZIP archive. Parameter is a Hash with following entries:

• root: root directory for files to include in the archive. Defaults to ’.’ for current directory.
• includes: glob or list of globs for files to select for the archive. Defaults to ’**/*’ to include all files recursively.
• excludes: glob or list of globs for files to exclude from the archive. Defaults to nil to exclude no file.
• dotmatch: tells if joker matches dot files. Optional, defaults to false.
• dest: the archive file to generate.
• prefix: prefix for archive entries (default to nil).

Example

 - zip:
     excludes: ["build/**/*", "**/*~"]
     dest:     :zip_archive

Note

If archive already exists, files are added to the archive.