Docs | Attachment Converter

1. Installation
2. Advanced Installation Options
- 2.1. .deb package
- 2.2. Building From Source

1. Installation

Attachment Converter (attc) is available for Arch Linux, Ubuntu, macOS, and Windows (via the Ubuntu WSL). Please see below for installation instructions.

1.1. Windows

There is no native Windows version of attc, but we maintain a version for Ubuntu version 26.04. This allows you to run attc under Ubuntu in your Windows Subsystem for Linux.

These instructions assume that you have Ubuntu WSL set up on your Windows machine. For a good guide to getting that set up, please consult these resources:

With your WSL set up, you can install attc by opening up a fresh WSL terminal and typing this command:

sudo add-apt-repository ppa:uchicago-dldc/attc

The purpose of this command is to make all of our Digital Library Development Center software packages avaiable for you to install, and it will prompt you for your WSL password. (Note that as you type your password, you won't see anything appear on the screen, but you should assume your password is being typed, and hit enter when you're done.) When you hit enter, if it's working, you should see a number of messages go by, including something that looks like this:

URIs: https://ppa.launchpadcontent.net/uchicago-dldc/attc/ubuntu/
Suites: resolute
Components: main
'
More info: https://launchpad.net/~uchicago-dldc/+archive/ubuntu/attc
Adding repository.

After that, you should see a series of messages about software packages downloading. Next, type this command:

sudo apt update

That command will check for updates. Finally, to install attc, type this command:

sudo apt install attc

It will print a long message telling you about all the Linux software packages it's going to install, then ask you to confirm by typing Y and hitting enter.

Congratulations! attc is now installed to your WSL. Please see our Guide for instructions on how to use attc.

1.2. macOS

On macOS, we recommend installing attc via our Digital Library Development Center Homebrew tap. If you don't have Hombrew installed on your Mac, we recommend first doing these two things:

do a full macOS update
open a macOS Terminal and run the command xcode-select --install

With that out of the way, please see this website for instructions on how to install Homebrew:

https://brew.sh/

With Homebrew set up, to install attc, please open your macOS Terminal app and type this command:

brew tap uchicago-library/attc

That will subscribe you to our Digital Library Development Center Homebrew tap for attc, so that you can install it in one command and easily get updates afterward. Homebrew may print some messages about how it is auto-updating when you run this command. Next, please run:

brew trust uchicago-library/attc

This tells Homebrew that you trust our website for distributing the application, and allows it to proceed with the install. Next, type this command to install attc to your Mac:

brew install attc

After you type the command, it will ask you to confirm. Type y to confirm. You should see a lot of installation messages get printed to the screen, and then at the end you'll see a message telling you to run this command:

Attachment Converter depends on LibreOffice for some functionality.

Please install it using:
  brew install --cask libreoffice

That last brew install command installs LibreOffice, which is what Attachment Converter uses to convert .doc file attachments in email.

Congratulations! attc is now installed on your Mac. Please see our Guide for instructions on how to use attc.

1.3. Arch Linux

attc is not currently available via the AUR, but if you are using Arch Linux and would like to install it, you can do so via our DLDC Arch Linux software repository. First, add the following to your /etc/pacman.conf:

[dldc]
SigLevel = Optional TrustAll
Server = http://dldc.lib.uchicago.edu/open/repos/arch

Then refresh your package databases:

pacman -Syy

That will make pacman aware of our software repository. When you run the -Syy, pacman will ask you to confirm that you trust our public key. The key it displays should be this:

3EF45886DF1EF82B4782F5FBD331DB7453444E0E

Once you have confirmed that you would like to add our repository, you can install attc in the usual way:

pacman -S attc

Congratulations! attc is now installed on your Arch box. Please see our Guide for instructions on how to use attc.

2. Advanced Installation Options

Although the above three options should work for most users on our three supported platforms, power users may prefer to install attc in other ways.

2.1. `.deb` package

If you are on Ubuntu but our PPA doesn't suit your needs, for whatever reason, you can find a .deb pacakge for attc here. To download:

wget https://dldc.lib.uchicago.edu/open/dist/attc/attc_0.2.12-1~resolute_amd64.deb

To install:

apt install ./attc_0.2.12-1~resolute_amd64.deb

2.2. Building From Source

2.2.1. Install `opam`

Attachment Converter is written in OCaml, which means that in order to build it, you need to install the opam package manager, which we recommend doing via your operating system's package manager. For example:

Arch Linux:

$ pacman -S opam

macOS:

$ brew install opam

WSL Debian:

$ apt install opam

Then, regardless of how you install opam, you need to initialize it in order to be able to use it.

$ opam init
$ eval $(opam env)

opam should then print some information to the console telling you about the steps it's taking to initialize.

That should be enough to get you going, but if you'd like more detailed information on how to install opam, please see the official installation instructions.

2.2.2. Install `opam` dependencies

To install all third-party library dependencies for Attachment Converter to your ~/.opam directory (which is where opam put the OCaml compiler and other packages it's going to use when you ran opam init), please run the following make rule from the root directory of the GitHub project you cloned:

$ cd /path/to/your/source/code/attachment-converter
$ make deps

This will make the Digital Library Development Center's very own opam repository available to you, then install all of Attachment Converter's third-party library dependencies. make deps should suffice for most purposes, but if you'd like to pursue the slightly fancier option of creating a sandboxed opam switch, you can instead run:

$ cd /path/to/your/source/code/attachment-converter
$ make sandbox

If you don't know what a sandboxed opam switch is, we suggest not worrying about it and going with the make deps rule.

2.2.3. Install OS-level dependencies

Next, you must install Attachment Converter's OS-level dependencies. For example:

Arch Linux:

$ pacman -S libreoffice pandoc libvips ghostscript poppler

macOS:

$ brew install libreoffice pandoc vips ghostscript verapdf poppler

WSL Debian:

$ apt install libreoffice pandoc vips ghostscript verapdf poppler-utils

2.2.4. Copy shell scripts to standard location

The shell scripts that Attachment Converter uses to invoke external conversion utilities are expected to be located at one of several specific filepaths. If you install attc via a package manager, the package manager will copy these shell scripts to whatever your host OS's preferred path to executable artefacts is. However, given that this is a manual installation, the best option is to place them in your home directory:

$ cd /path/to/your/source/code/attachment-converter
$ mkdir -p ~/.config/attachment-converter/scripts
$ cp conversion-scripts/*.sh ~/.config/attachment-converter/scripts

2.2.5. Time to Build

You should now be ready to build Attachment Converter. To build:

$ cd /path/to/your/source/code/attachment-converter
$ make

You can then install Attachment Converter by copying the binary to wherever you keep your binaries:

$ cd /path/to/your/source/code/attachment-converter
$ install -m 755 _build/default/main.exe /path/to/your/binaries/attc