.. _installation: Installation ============ .. contents:: Summary :depth: 2 :local: :backlinks: top 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 Debian package (recommended) ---------------------------------------- The Debian package comes with the preconfigured software and automatic downloading of the dependencies. The project is designed to run as a background service. Once installed, a udev rule will detect the connection of an Arduino interface on the machine and then start the service automatically. Download the .deb package in the assets of a release on the `GitHub repository `__. Install it: .. code-block:: bash $ sudo apt install ./libre-printer_1.0.0-3_all.deb A new dedicated ``libreprinter`` user will be created. List of files and folders of interest: ============================================ ================================================= `/var/lib/libre-printer/` Files generated by the interface and converters. `/lib/udev/rules.d/60-libre-printer.rules` Interface detection rule. `/lib/systemd/system/libre-printer@.service` Template of the System D service. `/etc/libre-printer/libreprinter.conf` Configuration file of the service. `/usr/share/libre-printer/` Project environment & code. `/usr/share/libre-printer/firmware/` Firmware and update scripts. `/usr/sbin/libreprinter` Service executable. ============================================ ================================================= After this simple step, you'll need to install a few dependencies that the project or your distribution does not include. See chapter :ref:`setting_up_dependencies`. .. _setting_up_multiple_printers: Configuring multiple interfaces on a single computer ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can create one udev rule per interface to start a pre-configured instance of the service. Each interface can therefore have its own configuration. You can connect as many interfaces as there are available USB ports. The default udev rule is in ``/lib/udev/rules.d/60-libre-printer.rules``: .. code-block:: SUBSYSTEM=="tty", ATTRS{idVendor}=="1b4f", ATTRS{idProduct}=="9206", SYMLINK+="ttyACMX", TAG+="systemd", ENV{SYSTEMD_WANTS}="libre-printer@ttyACMX.service" The Vendor ID and Product ID are the default values for an Arduino ProMicro. Such a configuration forces it to always appear with the path ``/dev/ttyACMX``. Upon connection, the System D service ``/lib/systemd/system/libre-printer@ttyACMX.service`` will be called if it exists. It is up to you to create a new udev rule and a service derived from the template ``/lib/systemd/system/libre-printer@.service`` by specifying a new configuration file (``libreprinter.conf``) for your printer (configuration file can be passed to the libreprinter binary via its command line as you will see in the System D file). Install the release version manually ------------------------------------ .. warning:: |project_name| is not published on PyPI for now. |project_name| 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: :ref:`setting_up_a_virtual_environment`. You can install the project with the following command on all systems with a Python environment with ``pip``: .. code-block:: bash $ 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: .. code-block:: bash $ libreprinter After this step, you'll need to install a few dependencies that the project or your distribution does not include. See chapter :ref:`setting_up_dependencies`. .. _install_dev_version: 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 |project_name|. First it is recommended to use a Python virtual environment; see the chapter below: :ref:`setting_up_a_virtual_environment`. Before installing the development version, you may need to uninstall the standard version of |project_name| using ``pip``: .. code-block:: bash $ pip uninstall libre-printer Then do: .. code-block:: bash $ 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 |project_name| at any time, in the same directory do: .. code-block:: bash $ 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 :ref:`setting_up_dependencies`. Uninstall ~~~~~~~~~ Just do: .. code-block:: bash $ make uninstall Testing ~~~~~~~ |project_name| uses the Python `pytest `_ testing package. You can test the packages from the source directory with: .. code-block:: bash $ make tests .. _setting_up_a_virtual_environment: 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: .. code-block:: bash $ pip install --user virtualenvwrapper * Edit your ``~/.bashrc`` or ``~/.zshrc`` file to source the ``virtualenvwrapper.sh`` script with these lines: .. code-block:: bash $ 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: .. code-block:: bash $ source ~/.bashrc * Create your virtualenv: .. code-block:: bash $ mkvirtualenv libreprinter -p /usr/bin/python3 * Later, if you want to work in the virtualenv: .. code-block:: bash $ workon libreprinter .. _setting_up_dependencies: 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 ************************** - `v10.0.0 linux-x86_64 (Artifex release) `_ - `v10.03.1 linux-armv6 (LibrePrinter release) `_ 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: .. code-block:: bash $ ./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.7 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 |project_name| 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: .. code-block:: bash $ 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). **Depending on the method selected, you will have to secure the accesses rights** of the assets by |project_name|. .. 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``: .. code-block:: bash # 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 {} \;