Skip to content

Commit

Permalink
Update installation instructions to emphasize virtual environments
Browse files Browse the repository at this point in the history
  • Loading branch information
@avanwinkle
avanwinkle committed Mar 11, 2024
1 parent f29815d commit 8c314f5
Show file tree
Hide file tree
Showing 5 changed files with 141 additions and 91 deletions.
13 changes: 6 additions & 7 deletions docs/install/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,20 +4,19 @@ title: Downloading & Installing MPF (2023 Version)

# Installing MPF

The current stable version of MPF is `0.56.x`.
The current stable version of MPF is `0.57.x`.

MPF should work with following platforms:

* Windows 10 / Windows 11 (64-bit only)
* macOS 10.14+, up through macOS 13 Ventura (Intel & Apple Silicon)
* Linux (64-bit, lots of distros)
* macOS 10.14+, up through macOS 14 Sonoma (Intel & Apple Silicon)
* Linux (64-bit, lots of distros including Debian and Ubuntu)
* Raspberry Pi

MPF 0.56 only works with Python 3.7 - 3.9.
MPF 0.57 works with Python 3.8 - 3.11. It is untested on 3.12, so your mileage may vary.

!!! note "MPF 0.57 supports Python 3.10 & 3.11"

MPF 0.57, which is the current `dev` branch of MPF, supports Python 3.8 - 3.11. See our [0.57 page](0.57.md) for details.
Regardless of your platform or Python version, a [virtual environment](virtual-environments.md) is
strongly recommended when working with MPF.

Here links to the installation guides for each platform:

Expand Down
9 changes: 4 additions & 5 deletions docs/install/linux/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,10 +31,10 @@ other platforms). Consult the README for more information.

## Installing MPF Manually

Current version these instructions are for v0.56.2, which is the current
Current version these instructions are for v0.57, which is the current
"main" branch of MPF.

MPF 0.56 requires Python 3.7, 3.8, or 3.9. Various Linux distributions
MPF 0.57 requires Python 3.8, 3.9, 3.10, or 3.11. Various Linux distributions
offer to install multiple versions of Python in parallel. First check
what version of Python you might have already running on your computer.

Expand All @@ -43,8 +43,7 @@ python3 --version
```

In some cases you might only get a Python version of 3.6, then run your
admin tool and install a higher version of python, preferably the latest
version of 3.9. If you don't want to remove the older version of Python
admin tool and install a higher version of python. If you don't want to remove the older version of Python
you can keep it in parallel, just make sure to run the installer
commands with the right version of python. If you have for example
installed Python 3.9 try to running
Expand Down Expand Up @@ -106,7 +105,7 @@ Now you should be ready to use mpf, for a first test run
mpf --version
```
You should see a version number printed, as time of writing it is 0.56.2. Maybe you see some higher
number. If you get a message that the command `mpf` is not being found or known you might have to add the location of the
number. If you get a message that the command `mpf` is not being found or known you might have to add the location of the
command to your `PATH` variable. Most likely (it depends on the shell type you use) you need to add to your `.profile` or `.bashrc` file an entry like

``` doscon
Expand Down
99 changes: 33 additions & 66 deletions docs/install/mac.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,67 +4,22 @@ title: Installing MPF on Mac

# Installing MPF on Mac

*Last updated Oct 13, 2023*
*Last updated Mar 10, 2024*

This guide will walk you through the process of installing MPF on a Mac. It's broken into two parts:

* Installing MPF 0.57 (current dev branch) on a Mac
* Installing MPF 0.56 (current stable branch) on a Mac

## Installing MPF 0.57 (dev) on a Mac
## Install Python

MPF 0.57 works on macOS running on both Intel and Apple Silicon (M1/M2
processors). For new installs, we recommend using Python 3.11, and that's
what these instructions will show. (MPF will work with Python 3.8 - 3.11.)

1. The easiest way to install MPF on a Mac is to use the [Homebrew package manager](https://brew.sh).
Open your command terminal and paste and run this command:

``` { .bash .copy}

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

```

This will also install the Xcode command line tools if you don't
have them. This process might take some time, so be patient.
2. Use Homebrew (or 'brew') to install the Python and the multimedia libraries MPF and MPF-MC need:
``` { .bash .copy}
brew install python@3.11 SDL2_mixer SDL2_image gstreamer
```
3. Install the various MPF packages. For example, to install MPF, MPF-MC, and MPF Monitor:
``` { .bash .copy}
pip3 install mpf mpf-mc mpf-monitor --pre
```
To check if you have python, type the following into your terminal:

Note that the `--pre` flag tells pip to install "pre-release" versions, which is how you get the
0.57 versions of these packages. If you omit that flag, you'll get 0.56 versions.
`python3 --version`

That's it! Skip down to the "Testing your MPF Installation" section to continue.
You should see some output like `Python 3.9.13`, which means you have
python installed and it's a supported version. If so, proceed to the next step.

## Installing MPF 0.56 (stable) on a Mac
!!! note "These instructions are for MPF 0.56"
These instructions are from 2022 for MPF 0.56. Every "MPF" reference below should be thought of as "MPF 0.56".
MPF works on macOS running on both Intel and Apple Silicon (M1/M2
processors). Requirements are:
* Apple Silicon Mac (M1/M2 processors) require macOS 12 Monterey or
newer and Python 3.9.
* Intel processors require MacOS 10.14 or newer, and Python 3.7 - 3.9.
* MPF does not work with Python 3.10+
To install MPF on a Mac:
To install Python on a Mac:

1. If you do not have Python, install Python 3.9.13 from python.org. If
you have an M1/M2 Mac, be sure to get the Universal installer, not
Expand Down Expand Up @@ -92,24 +47,41 @@ To install MPF on a Mac:

`brew install SDL2 SDL2_mixer SDL2_image gstreamer`

4. Verify that pip is installed. If you installed Python from
## Create a Virtual Environment

It's strongly recommended to create a virtual environment for MPF,
which will keep the installed packages from conflicting with other
applications on your computer. Before proceeding, follow the steps on
the [virtual environment installation guide](virtual-environments.md)

## Install MPF

First, activate the virtual environment you setup in the previous step.

1. Verify that pip is installed. If you installed Python from
python.org, then pip should have been installed as well. You can
verify this by running `pip --version` or `pip3 --version` in your
terminal. If it's not installed, you can install it using
`brew install pip`.
`python -m ensurepip`.

5. Use pip to install MPF with the Text UI components:
2. Use pip to install MPF:

`pip install "mpf[cli]"` or `pip3 install "mpf[cli]"`
`pip install "mpf"`

6. Use pip to install the MPF Monitor (Note that the latest version
requires PyQt6, priors required PyQt5):
or if you want to include the Text UI for debugging in the console,
install with the CLI parameter

`pip install mpf-monitor` or `pip3 install mpf-monitor`
`pip install mpf[cli]`

7. Use pip to install MPF-MC:
3. Use pip to install MPF-MC:

`pip install mpf-mc`

4. (Optional) Use pip to install the MPF Monitor (Note that the latest version
requires PyQt6, priors required PyQt5):

`pip install mpf-monitor`

`pip install mpf-mc` or `pip3 install mpf-mc`

Note: For the commands that use pip, if you run into permission issues,
try prefixing the command with sudo (i.e.,
Expand All @@ -127,11 +99,6 @@ If this works, you'll need to update your `~/.zshenv` file (or create one) with
ensure that variable is set for each terminal window launched. (ZSH is the shell for MacOS Catalina
and onward. If you're somehow still running something older, you'd edit the `~/.bash_profile` file instead).

Finally, pip installs Python packages globally by default. If you'd prefer
to keep your project and its dependencies isolated from your system's
Python, consider using a Python virtual environment. There are several
tools available for this, such as pipx, venv, or virtualenv.

## Testing your MPF installation with the mpf-examples repo

Now that MPF is installed, you probably want to test it out to make sure
Expand Down
77 changes: 77 additions & 0 deletions docs/install/virtual-environments.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
---
title: Using a Virtual Environment for MPF
---

# What is a Virtual Environment?

There are many versions of Python and many packages that can be installed, each
with its own dependencies on specific versions of other packages. A single Python
installation can get problematic if different installed packages depend on different
versions of the same package, and such dependency conflicts can cause bugs and even
prevent certain packages (like MPF) from running properly.

A "virtual environment" is a way to create an isolated, sandboxed environment for
a specific Python version. Packages installed in this environment are separate from
packages installed in other environments, including their dependencies.

**It is *highly recommended* to install MPF in a virtual environment.**

In fact, current releases of Debian (12) and Ubuntu (23) do not allow Python
packages to be installed outside of a virtual environment, so on those platforms
a virtual environment is required.

# Create a Virtual Environment

To create a virtual enviroment, choose a folder where you want to install
a copy of Python and keep the enviroment's packages. For this example, we'll
call the environment "mpfenv" and put it in our home directory (known as "~").

.. code-block:: console
python3 -m venv ~/mpfenv
.. note::

If you have multiple versions of Python3 (say, 3.9 and 3.11), you can specify
which one to use in the virtual environment: ``python3.9 -m venv ~/mpfenv``

A virtual environment is recommended for any general-use computer you'll be
using MPF on. For a dedicated MPF machine that will have no other programs
installed (for example, a computer inside a pinball cabinet), a virtual
environment is not required (except see above note regarding Debian and Ubuntu).

# Activate your Virtual Environment

To keep itself isolated from other programs, your virtual enviroment only
activates when you tell it to.
You can enable the virtual environment with the dot command from the terminal:

.. code-block:: console
. ~/mpfenv/bin/activate
Note that the first character is a period, followed by a space, then the path
to your virtual environment and "/bin/activate".

For users on Mac OSX, you will use `source` instead of the dot:

.. code-block:: console
source ~/mpfenv/bin/activate

.. note::

You may want to write this step down, as you'll run it every time you open up
a terminal window to work on MPF

You'll know you're in the virtual environment because the console prompt will include
the name of your venv in parenthesis.

.. code-block:: console
My-Mac:~ python --version
Python 2.7.10
My-Mac:~ source ~/mpfenv/bin/activate
(mpfenv) My-Mac:~ python --version
Python 3.9.13
(mpfenv) My-Mac:~
.. note::

The python you used to create the virtual environment will now be the
default python. Outside the virtual environment "python" is Python 2 and
you must type "python3" to use Python 3; inside the virtual environment,
you can use "python" to refer to Python 3.
34 changes: 21 additions & 13 deletions docs/install/windows.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ title: Installing MPF 0.56 on Windows

# Installing MPF on Windows

This process walks through installing MPF 0.56 a Windows machine.
This process walks through installing MPF 0.57 a Windows machine.

Note that installing MPF is more complicated than a normal application.
This is because MPF is a development tool you use to create your pinball
Expand Down Expand Up @@ -40,13 +40,14 @@ this command to check what is installed:
mpf --version
```

If you are using a virtual environment for MPF (recommended!) then
you don't need to uninstall anything, just create a new one.

## Windows System Requirements

MPF 0.56 requires Python 3.9. It does not run on Python 3.10 or newer.
(If you can figure out how to get it to run on Python 3.10+, please
submit the fixes!)
MPF 0.57 requires Python 3.9, 3.10, or 3.11.

MPF can run on Python 3.7 and 3.8, but the MPF-MC audio doesn't work on
MPF can run on 3.8, but the MPF-MC audio doesn't work on Windows in
those versions. So you should use Python 3.9.

## Install Python
Expand Down Expand Up @@ -79,13 +80,20 @@ You want a result like "Python 3.9.13" or whatever version you just
installed. If you see a version other than that, trying running
`python3 --version` instead.

## Create a Virtual Environment

It's strongly recommended to create a virtual environment for MPF,
which will keep the installed packages from conflicting with other
applications on your computer. Before proceeding, follow the steps on
the [virtual environment installation guide](virtual-environments.md)

## Install MPF

Now you're ready to install MPF. Open a new command window (cmd.exe)
and type these commands and hit enter.
Now you're ready to install MPF. Open a new command window (cmd.exe),
activate your virtual environment, and type these commands and hit enter.

``` doscon
pip install "mpf[cli]"
pip install "mpf"
```

A bunch of things will scroll by, and then hopefully MPF is installed.
Expand All @@ -95,7 +103,7 @@ You can test it by typing this command:
mpf --version
```

This should print out something like [MPF 0.56.0](#). If you
This should print out something like [MPF 0.57.0](#). If you
get an error, something went wrong. If you get a different version, then
you might have an older version of MPF which you need to uninstall
first. (See the "Remove prior versions of MPF" section above.)
Expand Down Expand Up @@ -129,7 +137,7 @@ most do. (There are also other media controllers that are not MPF-MC.
For example, some people use Unity, the Unreal Engine, or Godot as their
media controllers.)

To install MPF-MC, use the following command:
To install MPF-MC, open your virtual environment and use the following command:

``` doscon
pip install mpf-mc
Expand All @@ -147,17 +155,17 @@ it installs doesn't mean it works. :(
Dec. 2023 Note: mc_demo and demo_man aren't working, but you can get
the demo_man loading screen to display after performing the following:

Because 0.56 is the current release, download the `0.56.x` branch of
Because 0.57 is the current release, download the `0.57.x` branch of
the `mpf-examples` repo from here:
<https://github.com/missionpinball/mpf-examples>.

![image](images/version-select.png)

You can download the zip file and unzip it, or clone it. If you
download the `dev` branch, you will have config version mismatch
download the `dev` branch, you will have config version mismatch
issues.

From the commmand terminal, change to the `mpf-examples-0.56.x`
From the commmand terminal, change to the `mpf-examples-0.57.x`
directory, where ever it was downloaded. Then, change to the
`demo_man` directory. Finally, run the following command:

Expand Down

0 comments on commit 8c314f5

Please sign in to comment.