Skip to content

Commit

Permalink
Recommend installing with pipx instead of pip
Browse files Browse the repository at this point in the history
Closes #312
  • Loading branch information
Cimbali committed May 14, 2024
1 parent 6a7df6a commit 316a56f
Show file tree
Hide file tree
Showing 2 changed files with 51 additions and 13 deletions.
43 changes: 38 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -85,18 +85,51 @@ Here is what the 2 screen setup looks like, with a big notes slide next to 2 sma
- Other systems, directly from PyPI ![pypi version badge][pypi_version] − requires [python, gtk+3, poppler, and their python bindings](#dependencies):

```
python3 -m pip install "pympress"
pipx install --system-site-packages "pympress"
```

<details><summary>Troubleshooting</summary>

- Make sure you have all [the dependencies](#dependencies). (These are already included in binary packages or their dependencies.)
- Using pip, you may want to install with the `--user` option, or install from github or downloaded sources.
See [the python documentation on installing](https://docs.python.org/3.7/installing/index.html).
- If your python environment lacks the Gobject Introspections module, try
1. using `--system-site-packages` for [virtual environments](https://docs.python.org/3.7/library/venv.html),
2. installing pygobject from pip (`pip install pygobject`, which requires the correct development/header packages.
1. using `--system-site-packages` for [pipx](https://pipx.pypa.io/latest/docs/#pipx-install)
or [virtual environments](https://docs.python.org/3.11/library/venv.html),
2. installing pygobject and pycairo with pipx (`pipx inject pympress pygobject pycairo`),
which requires the correct development/header packages be present on your system.
See [the PyPI installation instructions of PyGObject for your system](https://pygobject.readthedocs.io/en/latest/getting_started.html)).
- As per [the python documentation on installing](https://docs.python.org/3.11/installing/index.html),
it is recommended to install packages in virtual environments.
Since mid 2022, the [pipx](https://packaging.python.org/en/latest/key_projects/#pipx) tool automates this process.
Your distribution (or Homebrew on macOS) should have a version you can install.
Alternately, you can get the same effect with the standard venv and pip modules:
```sh
# Create virtual environment
python3 -m venv --system-site-packages ~/.local/lib/venv/pympress
# Install pympress
~/.local/lib/venv/pympress/bin/python3 -m pip install pympress
# Link to the executable from a place in your path
ln -s ~/.local/lib/venv/pympress/bin/pympress ~/.local/bin/
```
Note that:
- If you don’t want to use system packages, you can build and install pygobject/pycairo in the virtual environment using
`~/.local/lib/venv/bin/pip install pygobject pycairo`
- You can adjust the `~/.local/lib/venv/` path to your personal preference.
- Unfortunately, installing pympress in a virtual environment means you will not get desktop integration
(i.e. installing pympress' desktop and png files to have pympress show up in your menus etc).
This is [by design](https://discuss.python.org/t/should-there-be-a-new-standard-for-installing-arbitrary-data-files/7853/4),
as desktop applications are intended to be installed through system packages (rpm, apt, etc.).
You can work around this in 2 ways:
1. Manually (note that links/copied files will need to be removed):
```sh
cp "`pipx environment -V PIPX_LOCAL_VENVS`/pympress/share/applications/io.github.pympress.desktop" ~/.share/applications/
ln -s "`pipx environment -V PIPX_LOCAL_VENVS`/pympress/share/pixmaps/pympress.png" ~/.share/pixmaps/
```
2. Relying on the deprecated data_files, that only work [outside of virtual environments](https://peps.python.org/pep-0668/).
This means installing with `pip`:
```sh
python3 -m pip install --user --break-system-packages pympress
```
</details>
Expand Down
21 changes: 13 additions & 8 deletions pympress/__main__.py
Original file line number Diff line number Diff line change
Expand Up @@ -89,14 +89,19 @@ def uncaught_handler(*exc_info):
import cairo
except ModuleNotFoundError:
logger.critical('Gobject Introspections and/or pycairo module is missing', exc_info = True)
print('\n' + _('ERROR: Gobject Introspections and/or pycairo module is missing, ' +
'make sure Gtk, pygobject and pycairo are installed on your system.') + '\n')
print(_('Try your operating system’s package manager, or try running: pip install pygobject pycairo'))
print(_('pip will then download and compile pygobject and pycairo, ' +
'for which you need the Gtk and cairo headers (or development packages).') + '\n')
print(_('For instructions, refer to https://github.com/Cimbali/pympress/blob/master/README.md#dependencies'))
print(_('If using a virtualenv or anaconda, you can also try allowing system site packages.'))
print()
print(_("""
ERROR: Gobject Introspections and/or pycairo module is missing. Make sure Gtk, pygobject and pycairo are installed.
Try your operating system’s package manager, and ensure you installed pympress with access to system packages.
Typically, this means having installed with:
pipx install --system-site-packages pympress
Alternately, ask pip to download and compile pygobject and pycairo, for which you may need the Gtk and cairo headers
(or development packages):
pipx inject pympress pygobject pycairo
For further instructions, refer to https://github.com/Cimbali/pympress/blob/master/README.md#dependencies
"""))
exit(1)


Expand Down

0 comments on commit 316a56f

Please sign in to comment.