Skip to content

Commit

Permalink
Rework run from source section for Linux and macOS
Browse files Browse the repository at this point in the history
  • Loading branch information
@rockstorm101
rockstorm101 committed Aug 16, 2023
1 parent 0f3cd9a commit 12032bf
Showing 1 changed file with 86 additions and 67 deletions.
153 changes: 86 additions & 67 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -56,8 +56,8 @@ repositories or from PyPI. If you want the newest, shiniest features, you can
Everything bundled into one single package for easy installation. Downloads
available at: https://github.com/kliment/Printrun/releases/latest

> Note for OSX users: if OSX tells you `"pronterface.app" cannot be opened
> because the developer cannot be verified.`, you don't need to redownload
> **Note for OSX users**: if OSX tells you `"pronterface.app" cannot be opened
> because the developer cannot be verified.`, you don't need to re-download
> it. Instead, you need to allow OSX to run the unsigned app. To do this,
> right click the application in Finder and select `Open`. Then click `Open`
> in the popup window that appears. You only need to do this once.
Expand Down Expand Up @@ -106,7 +106,7 @@ Packages are available in AUR. Just run

If you have a working Python environment, regardless of your OS, you can
install the latest release distributed through the PyPI repository using
[pip][2] and, optionally (but highly recommended), [venv][3].
[pip][2] and, optionally (but highly recommended), a [virtual environment][3].

Activate your virtual environment, and run (Linux / macOS):

Expand All @@ -120,60 +120,99 @@ or (Windows):
[2]: https://pip.pypa.io/
[3]: https://docs.python.org/3/tutorial/venv


## Running From Source

Run Printrun for source if you want to test out the latest features.
By running Printrun from source you get access to the latest features and
in-development changes. Warning note: these might not be fully working or
stable.

### Dependencies
### Linux / macOS

To use pronterface, you need:
#### 1. Install Python

* Python 3 (ideally 3.10),
* pyserial (or python3-serial on ubuntu/debian)
* pyreadline (not needed on Linux)
* wxPython 4
* pyglet
* appdirs
* numpy (for 3D view)
* pycairo (to use Projector feature)
* cairosvg (to use Projector feature)
* dbus (to inhibit sleep on some Linux systems)
Almost all Linux distributions come with Python already pre-installed. If not,
install Python normally from your package manager. On macOS download and
install the latest Python from [python.org][4].

### Use Python virtual environment
[4]: https://www.python.org/downloads/macos/

Easiest way to run Printrun from source is to create and use a Python [virtual environment](https://docs.python.org/3/tutorial/venv.html).
The following section assumes Linux. Please see specific instructions for Windows and macOS below.

**Ubuntu/Debian note:** You might need to install `python3-venv` first.
#### 2. Download the latest Printrun source code

**Note:** wxPython4 doesn't have Linux wheels available from the Python Package Index yet. Find a proper wheel for your distro at [extras.wxpython.org](https://extras.wxpython.org/wxPython4/extras/linux/gtk3/) and substitute the link in the below example. You might skip the wheel installation, but that results in compiling wxPython4 from source, which can be time and resource consuming and might fail.
Obtain the latest source code by running the following in a terminal window:


```console
```shell
$ git clone https://github.com/kliment/Printrun.git # clone the repository
$ cd Printrun # change to Printrun directory
$ python3 -m venv venv # create an virtual environment
$ . venv/bin/activate # activate the virtual environment (notice the space after the dot)
(venv) $ python -m pip install https://extras.wxpython.org/wxPython4/extras/linux/gtk3/fedora-27/wxPython-4.0.1-cp36-cp36m-linux_x86_64.whl # replace the link with yours
```


#### 3. Use a Python virtual environment

Easiest way to run Printrun from source is to create and use a Python [virtual
environment][3]. This step is optional but highly recommended to avoid
conflicts with other Python libraries already installed (or that will be
installed in the future) in your system. Within the Printrun's root directory,
create and activate a virtual environment by running:

```shell
$ python -m venv venv # create a virtual environment
$ source venv/bin/activate # activate the virtual environment
```

> **Note for Ubuntu/Debian**: You might need to install `python3-venv` first.
> **Note for Ubuntu/Debian**: If you get `python: command not found` use
> `python3` instead of just `python` on all commands below.

#### 4. Install dependencies

Dependencies for running Printrun are laid out in the [`requirements.txt`][5]
file. Once activated your virtual environment, install required dependencies
with:

```
(venv) $ python -m pip install -r requirements.txt # install the rest of dependencies
(venv) $ python pronterface.py # run Pronterface
```

### Cython-based G-Code parser
> **Note for Linux users**: wxPython4 doesn't have Linux wheels available from
> the Python Package Index yet. Before running the command above, find a
> proper wheel for your distro at [extras.wxpython.org][6] and substitute the
> link in the below example. You might skip this wheel installation, but that
> results in compiling wxPython4 from source, which can be time and resource
> consuming and might fail.
> ```shell
> (venv) $ python -m pip install https://extras.wxpython.org/wxPython4/extras/linux/gtk3/fedora-27/wxPython-4.0.1-cp36-cp36m-linux_x86_64.whl # replace the link with yours
> ```
Printrun default G-Code parser is quite memory hungry, but we also provide a much lighter one which just needs an extra build-time dependency (Cython), plus compiling the extension with:
[5]: requirements.txt
[6]: https://extras.wxpython.org/wxPython4/extras/linux/gtk3
#### 5. (Optional) Cython-based G-Code parser
Printrun default G-Code parser is quite memory hungry, but we also provide a
much lighter one which just needs an extra build-time dependency (Cython). The
warning message `WARNING:root:Memory-efficient GCoder implementation
unavailable: No module named gcoder_line` means that this optimized G-Code
parser hasn't been compiled. To get rid of it and benefit from the better
implementation, install Cython and build the extension with the following
commands:
```console
(venv) $ python -m pip install Cython
(venv) $ python setup.py build_ext --inplace
```
The warning message
WARNING:root:Memory-efficient GCoder implementation unavailable: No module named gcoder_line
#### 6. Run Printrun
means that this optimized G-Code parser hasn't been compiled. To get rid of it and benefit from the better implementation, please install Cython and run the command above.
With your virtual environment still active, invoke the app you need like:
```shell
(venv) $ python pronterface.py # or `pronsole.py` or `plater.py`
```
### Windows
Expand Down Expand Up @@ -204,26 +243,6 @@ Run Pronterface or Pronsole from the binary files or from source calling pronter
Run 'release_windows.bat' when ever you make changes or updates. With each new run it will compile the binaries and update all involved libraries in the virtual environment if needed. Delete the virtual environment if you have problems with it. Use 'git submodule update --init --recursive' for updating the submodule
### macOS

Install Python 3, you can use Brew:

```console
$ brew install python3
```

Then continue to install and set up Printrun:

```console
$ git clone https://github.com/kliment/Printrun.git # clone the repository
$ cd Printrun # change to Printrun directory
$ python3 -m venv venv # create an virtual environment
$ . venv/bin/activate # activate the virtual environment (notice the space after the dot)
(venv) $ python -m pip install -r requirements.txt # install the rest of dependencies
# follow instructions for cython gcoder here if desired
(venv) $ python pronterface.py # run Pronterface
```

# USING PRINTRUN
Expand Down Expand Up @@ -539,7 +558,7 @@ List of available commands:
# TESTING
A small (work in progress) test suite is developed within folder `tests` using
[unittest][4] which can be run with (requires Python 3.11+):
[unittest][8] which can be run with (requires Python 3.11+):
```
python -m unittest discover tests
Expand All @@ -549,7 +568,7 @@ Small utilities for testing/debugging communications or g-code reading/writing
are also provided within folder `testtools`.
[4]: https://docs.python.org/3/library/unittest
[8]: https://docs.python.org/3/library/unittest
# CONTRIBUTING
Expand All @@ -564,7 +583,7 @@ anyone. There are many ways to contribute:
being brought up to date.
* Submitting bug reports and feature requests.
- We use GitHub's [issue tracker][5] to keep track of them.
- We use GitHub's [issue tracker][9] to keep track of them.
- Please remember to state your OS and Printrun version on new issues.
* Improving the test code base. Current code coverage is extremely low. See
Expand All @@ -574,23 +593,23 @@ anyone. There are many ways to contribute:
fair amount of known issues and a great deal of requested features waiting
to be implemented. We (the maintainers) don't have the time and resources
to look at them all so every code contribution will be very welcome.
- We use GitHub's [pull requests][6] to review and incorporate new code.
- Issues labeled [`Regression`][8] would be the most urgent fixes needed,
followed by issues/requests labeled [`2.x`][9] and lastly those with
[`3.x`][10].
- Ideally every new contribution should comply with [PEP 8][7] style guide
- We use GitHub's [pull requests][10] to review and incorporate new code.
- Issues labeled [`Regression`][11] would be the most urgent fixes needed,
followed by issues/requests labeled [`2.x`][12] and lastly those with
[`3.x`][13].
- Ideally every new contribution should comply with [PEP 8][14] style guide
as much as possible and should be thoroughly documented to ease reviewing
and future understanding of the code.
- Please note that breaking changes might need to wait to be incorporated
until the next major release is due.
[5]: https://github.com/kliment/Printrun/issues
[6]: https://github.com/kliment/Printrun/pulls
[7]: https://peps.python.org/pep-0008
[8]: https://github.com/kliment/Printrun/labels/Regression
[9]: https://github.com/kliment/Printrun/labels/2.x
[10]: https://github.com/kliment/Printrun/labels/3.x
[9]: https://github.com/kliment/Printrun/issues
[10]: https://github.com/kliment/Printrun/pulls
[14]: https://peps.python.org/pep-0008
[11]: https://github.com/kliment/Printrun/labels/Regression
[12]: https://github.com/kliment/Printrun/labels/2.x
[13]: https://github.com/kliment/Printrun/labels/3.x
# CONTRIBUTORS
Expand Down

0 comments on commit 12032bf

Please sign in to comment.