## Cab

### Description

The cab task creates Microsoft cabinet archive files. It is invoked similar to the jar or zip tasks. This task will work on Windows using the external `cabarc` tool (provided by Microsoft) which must be located in your executable path.

To use this task on other platforms you need to download and compile `libcabinet` from https://www.freshports.org/archivers/libcabinet/.

See the section on directory based tasks, on how the inclusion/exclusion of files works, and how to write patterns.

This task forms an implicit FileSet and supports most attributes of `<fileset>` (dir becomes basedir) as well as the nested `<include>`, `<exclude>` and `<patternset>` elements.

On non-Unix platforms this task writes the list of files to archive to the temporary directory.

### Parameters

Attribute | Description | Required
--- | --- | ---
cabfile | the name of the cab file to create. | Yes
basedir | the directory to start archiving files from. | No
verbose | set to yes if you want to see the output from the `cabarc` tool. | No; defaults to no
compress | set to no to store files without compressing. | No; defaults to yes
options | set additional command-line options for the `cabarc` tool. Should not normally be necessary. | No
includes | comma- or space-separated list of patterns of files that must be included. | No; defaults to all (**)
includesfile | name of a file. Each line of this file is taken to be an include pattern | No
excludes | comma- or space-separated list of patterns of files that must be excluded. | No; defaults to default excludes or none if defaultexcludes is no
excludesfile | name of a file. Each line of this file is taken to be an exclude pattern | No
defaultexcludes | indicates whether default excludes should be used or not (yes|no). | No; defaults to yes

### Parameters specified as nested elements

#### fileset

The cab task supports one nested `<fileset>` element to specify the files to be included in the archive. If this is specified, the basedir attribute cannot be used.

### Examples

Cab all files in the `htdocs/manual` directory into a file called `manual.cab` in the `${dist}` directory.

    <cab cabfile="${dist}/manual.cab"
         basedir="htdocs/manual"/>

Cab all files in the `htdocs/manual` directory into a file called `manual.cab` in the `${dist}` directory. Files in the directory `mydocs`, or files with the name `todo.html` are excluded.

    <cab cabfile="${dist}/manual.cab"
         basedir="htdocs/manual"
         excludes="mydocs/**, **/todo.html"/>

Cab all files in the `htdocs/manual` directory into a file called `manual.cab` in the `${dist}` directory. Only `.html` files under the directory `api` are archived, and files with the name `todo.html` are excluded. Output from the `cabarc` tool is displayed in the build output.

    <cab cabfile="${dist}/manual.cab"
         basedir="htdocs/manual"
         includes="api/**/*.html"
         excludes="**/todo.html"
         verbose="yes"/>

The following is equivalent to the example above.

    <cab cabfile="${dist}/manual.cab"
         verbose="yes">
      <fileset
           dir="htdocs/manual"
           includes="api/**/*.html"
           excludes="**/todo.html"/>
    </cab>