The executable is invoked with the following syntax:

```
./bc-zip command <command-specific options>
```

The most interesting commands are the following:

`bit-optimal`

: compress the file so compresson ratio is maximized`compress`

: optimize one resource (decompression speed, compression ratio) given a bound on the other one.`decompress`

: decompress a file

There are also two commands, namely encoders and gens, which we will illustrate later in this document.

We report the most important options (bold options are compulsory). For others, have a look at the command-line help
(just type `bc-zip bit-optimal`

to show the help).

Option | Meaning |
---|---|

-i file |
File to be compressed. Can also be specified by the first positional argument. |

-o file |
Filename of compressed output. Can also be specified by the second positional argument. |

-e encoder |
Integer encoder used in compression. A list of all supported encoders can be retrieved by invoking the bc-zip command “encoders”. We suggest to pick one among `soda09_16` (succinct, relatively slow at decompression) and `hybrid-16` (less succinct, very fast decompression speeds). |

-b bucket | Logically splits the input file into blocks of bucket megabytes, compresses them individually and then concatenate them to obtain the final compressed file. Lowers compression time at the expense of optimality and, thus, compression ratio. |

-z | Shows a progress bar while compressing. |

**Examples**:

```
./bc-zip bit-optimal input output.lzo -e hybrid-16 -b 64
```

Compress file `input`

into `output.lzo`

, using the fast encoder `hybrid-16`

, with buckets of `64`

megabytes.

```
./bc-zip bit-optimal input output.lzo -e soda09_16 -z
```

Optimally compress file `input`

into `output.lzo`

, using the succinct encoder `soda09_16`

.

Compress implements “bicriteria” compression.
In order to evaluate decompression times, a **target** file encoding the decompression time model for the target machine (that is, the machine in which decompression will take place) is required. Have a look at section Target files for more informations about this matter.

In the following we illustrate the most important options (bold options are compulsory).

Option | Meaning |
---|---|

-i file |
File to be compressed. Can also be specified by the first positional argument. |

-e encoder |
Integer encoder used in compression. A list of all supported encoders can be retrieved by invoking the bc-zip command “encoders”. We suggest to pick one among soda09_16 (succinct, relatively slow at decompression) and hybrid-16 (less succinct, very fast decompression speeds). |

-t target |
Specify the target machine model file, as obtained by the calibrator tool (see the section about the calibrator for further informations), WITHOUT the .tgt suffix. That is, if the model is names X.tgt, then just pass X to this option. |

-b bound |
Specify the compression bound. If the bound has the form XK/M, then the compression size will be at most X kilobytes/megabytes and the decompression time minimized. If the bound has the form Xm/s, then the decompression time will be at most X milliseconds/seconds (according to the target model specified with option -t ) and compressed size minimized. Multiple bounds can be specified by separating different bounds with a comma: in this case the file will be compressed multiple times, once for each bound. |

-l level | Specify a compression level (float in range [0,1]), which might be in compression space or decompression time. A compression level is a “relative” way of setting bounds. A level in the form XS (such as 0.5S) defines a bound on the compression space. It means that, if the most space-succinct compressed file for the input file has space S_1, and the compressed file with the highest decompression speed has space S_2 (with S_1 < S_2), then the level specifies a bound on compressed space equal to S_1 + X * (S_2 - S_1). In other words, compressing a file with level 0S is the same as compressing the file with the bit-optimal command, while compressing a file with level 1S instructs the compressor to obtain the decompression time-optimal compression file. Linearly increasing the level increases linearly the compressed space of the final parsing. A level in the form XT (such as 0.2T) similarly defines a bound on the decompression time, so a level of 0T obtains the compression with the lowest decompression time, while a level of 1T obtains the most succinct compressed file. A level of 0.5T has a decompression time which is a mean of the decompression time of the most succinct compressed file and the decompression time of the compressed file with the highest decompression speed. Multiple levels can be specified by separating different bounds with a comma: in this case the file will be compressed multiple times, once for each level. |

-z | Shows a progress bar while compressing. |

At least one among -b or -l must be selected. The output file name is a combination of the input file name and the compression options specified.

**Examples**

Suppose you have a file `input.txt`

to be compressed and a target file `smartphone.tgt`

, which models the decompression time of a compressed file on a particular smartphone.
Suppose the most succinct compressed file has a decompression time of 600 msec (with encoder `hybrid-16`

) and takes 200MB, while the fastest compressed file is decompressed in 300msec (also with encoder `hybrid-16`

) and takes 400MB of space.
Then:

```
./bc-zip compress input.txt -e hybrid-16 -t smartphone -b 300M -z
```

Compress file `input.txt`

with encoder `hybrid-16`

, obtaining the fastest compressed file which is not greater than 300 megabytes (300 * 2^{20} bytes), showing a progress bar during the process. The compressed file is `input.txt#hybrid-16#300MB.lzo`

.

```
./bc-zip compress input.txt -e soda09_16 -t smartphone -b 300M,400m
```

Compress file `input.txt`

two times with encoder `soda09_16`

: the first time with a bound of 300MB (300 * 2^{20} bytes) in space, saving in `input.txt#soda09_16#300MB.lzo`

; the second with a time bound of 400 msecs (according to model `smartphone.tgt`

, stored in the calling directory), saving in `input.txt#soda09_16#400msec.lzo`

```
./bc-zip compress input.txt -e hybrid-16 -t smartphone -l 0.5T,0.1T,0.1S -b 300M
```

Compress file input.txt four times:

- first time with a level of
`0.5T`

, so with a time bound of 450 msec (remember the assumptions made at the beginning), saving in`input.txt#hybrid-16#0.5T.lzo`

- second time with a level of
`0.1T`

, so with a time bound of 330 msec, saving in`input.txt#hybrid-16#0.5T.lzo`

- third time with a level of
`0.1S`

, so with a space bound of 220MB, saving in`input.txt#hybrid-16#0.1S.lzo`

- fourth time with a bound of 300MB, saving in
`input.txt#hybrid-16#300MB.lzo`

Usage: bc-zip decompress input_file output_file

**Example**

```
./bc-zip decompress compressed.lzo original
```

Decompress file `compressed.lzo`

into file `original`

.