Installation

Foreword

Language used

All the main code is developped in Python3.6+ language.

However external programs like ESC converters are written in C or C++. This is the choice of the programmers depending on their preferences or by desire to hide their work and make their project not modifiable (ex: the binaries of Retroprinter).

System requirements

A functional Python3 environment must be installed on your computer if you choose to not install the Debian package (i.e. for manual installation).

For the eventual compilation of external binaries, you may need a GCC/G++ based build chain.

Most/all of these requirements are already installed on basic GNU/Linux systems.

Install the release version manually

Warning

Libre-Printer is not published on PyPI for now.

Libre-Printer package is available on PyPI (Python Package Index), the official third-party software repository for Python language: LibrePrinter service.

We recommend first the use of a Python virtual environment; see the chapter below: Setting up a Python virtual environment for a manual installation.

You can install the project with the following command on all systems with a Python environment with pip:

$ pip install libre-printer

Note

Don’t forget to add the flag --user to the command above if you don’t use virtual environment or if you do not have root privileges on your system.

At this point a new command is available in your shell to launch the service:

$ libreprinter

After this step, you’ll need to install a few dependencies that the project or your distribution does not include. See chapter Install the external dependencies.

Install the development version

Install from sources

If you have Git installed on your system, it is also possible to install the development version of Libre-Printer.

First it is recommended to use a Python virtual environment; see the chapter below: Setting up a Python virtual environment for a manual installation.

Before installing the development version, you may need to uninstall the standard version of Libre-Printer using pip:

$ pip uninstall libre-printer

Then do:

$ git clone https://github.com/ysard/libre-printer
$ cd libre-printer
$ make dev_install

The make dev_install command uses pip install -e .[dev] command which allows you to follow the development of the git repository.

Moreover, it installs for you the dev packages listed in the extras_require section of setup.py/setup.cfg, in addition to any basic dependencies.

Please note that your changes in the code are directly testable without having to reinstall the package.

Then, if you want to update Libre-Printer at any time, in the same directory do:

$ git pull

After this simple step, you’ll need to install a few dependencies that the project or your distribution does not include. See chapter Install the external dependencies.

Uninstall

Just do:

$ make uninstall

Testing

Libre-Printer uses the Python pytest testing package.

You can test the packages from the source directory with:

$ make tests

Setting up a Python virtual environment for a manual installation

As always, the use of a Python virtual environment (via virtualenvwrapper) is strongly advised at least for development purposes.

This is not a mandatory step but it is a good and a simple practice to separate projects from each other in order to avoid conflicts between dependencies.

  • Install virtualenvwrapper:

$ pip install --user virtualenvwrapper

  • Edit your ~/.bashrc or ~/.zshrc file to source the virtualenvwrapper.sh script with these lines:

$ export PATH=$PATH:~/.local/bin
$ export WORKON_HOME=~/.virtualenvs
$ mkdir -p $WORKON_HOME
$ # The location of this script may vary depending on your GNU/Linux distro
$ # and depending of your installation procedure with pip.
$ # See ~/.local/bin/ or /usr/bin
$ source ~/.local/bin/virtualenvwrapper.sh

  • Restart your terminal or run:

$ source ~/.bashrc

  • Create your virtualenv:

$ mkvirtualenv libreprinter -p /usr/bin/python3

  • Later, if you want to work in the virtualenv:

$ workon libreprinter

Install the external dependencies

GhostPCL

If you plan to use LibrePrinter with a computer that sends data in the HP PCL format, you’ll need the GhostPCL utility developed by the GhostScript team.

There are currently 2 installation methods:

  • If you choose to use a (Raspbian) image provided by the RetroPrinter company you have nothing to do, GhostPCL is integrated.

  • If you’re not using an image provided by the RetroPrinter company, there is a little work to do (download our compiled version or compile it yourself).

GhostPCL is not available in the Debian repositories because of conflicts with system libraries. However, you can download the sources/some binaries here: GhostPdl downloads on GitHub

Warning

Note that GhostScript no longer supplies compiled binaries for GNU/Linux since version 10.0.0 (Sept. 2022). You can download this specific version, or a recent version to be compiled.

The key move is to always sync the path of the gpcl6 binary in the parameter pcl_converter_path of the config file libreprinter.conf (default is /usr/local/bin/gpcl6).

Download compiled binaries

Then copy the gpcl6 binary to /usr/local and make it executable (chmod 755 /usr/local/gpcl6).

Compilation

Compiling sources is easy (but takes time); First, download and extract the archive (for example: ghostpdl-10.03.1.tar.xz), then:

$ ./configure
$ make -j 2
$ make install # Will install the binaries in /usr/local by default

RetroPrinter vendor blobs

Warning

Until now, only the convert-escp2 binary v3.4 is available on x86_64. Other binaries, updates & platforms should come, but in the meantime you will have to use the ARM binaries vendor blobs provided by the RetroPrinter company. Reverse-engineering is a tough job…

Keep up to date with the latest developments in the GitHub repository.

There are currently 3 installation methods.

  • If you choose to use a (Raspbian) image provided by the RetroPrinter company, at the very least, you’ll need to modify the rights of the existing folders so that converters launched by the Libre-Printer service can operate safely with their needed assets.

  • You can use our packaged binaries, with an embedded installation script.

    • Just download the last vendor_blobs_xx.yy_armv6.tar.gz archive: GitHub releases.

    • Make sure ACLs are available on your system (apt install acl).

    • Then:

    $ tar xvf vendor_blobs_xx.yy_armv6.tar.gz
$ cd vendor_blobs/
$ sudo ./install_vendor_blobs.sh

    You are ready to go!

  • If you’re not using an image provided by the RetroPrinter company, you’re free to place the binaries wherever you like, but don’t forget these 2 points:

    • Update the paths of the binaries in the file /etc/libreprinter.conf

    • Until now, RetroPrinter binaries require assets to be placed in specific folders. The config files must be put in the folder /root/config, the fonts must be put in /home/pi/temp/sdl/escparser/fonts.

    • Access rights must be fixed (see below).

If you choose a non-standard installation method, you will have to secure the accesses rights of the assets by Libre-Printer.

Note

The paths involved are atypical, even amateurish and dangerous (most of accesses are for root, and their programs also run as root… like SysAdmins say, using root or chmod 777 for everything is the best way to prove you don’t know what you’re doing.), but hey, it’s not our fault!

The following ACLs (Access Control List) rules will fix the rights for the user libreprinter:

# Install the ACL tools
$ apt-get install acl

# Fix access rights for the config files
$ setfacl -m u:libreprinter:x /root/
$ setfacl -m u:libreprinter:rx /root/config
$ find /root/config/ -type f -exec setfacl -m u:libreprinter:r {} \;

# Fix access & execution rights for the converters and the fonts
$ setfacl -m u:libreprinter:x /home/pi
$ setfacl -R -m u:libreprinter:rx /home/pi/temp
$ find /home/pi/temp/sdl/escparser/fonts/ -type f -exec setfacl -m u:libreprinter:r {} \;