diff --git a/docs/install/index.md b/docs/install/index.md index 3d9f394e15..2bed2b9497 100644 --- a/docs/install/index.md +++ b/docs/install/index.md @@ -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: diff --git a/docs/install/linux/index.md b/docs/install/linux/index.md index ff7dff05ba..415898e763 100644 --- a/docs/install/linux/index.md +++ b/docs/install/linux/index.md @@ -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. @@ -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 @@ -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 diff --git a/docs/install/mac.md b/docs/install/mac.md index 267ef1472c..68c97a572d 100644 --- a/docs/install/mac.md +++ b/docs/install/mac.md @@ -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 @@ -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., @@ -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 diff --git a/docs/install/virtual-environments.md b/docs/install/virtual-environments.md new file mode 100644 index 0000000000..726ba4be6d --- /dev/null +++ b/docs/install/virtual-environments.md @@ -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. \ No newline at end of file diff --git a/docs/install/windows.md b/docs/install/windows.md index 501b407ab1..666e858664 100644 --- a/docs/install/windows.md +++ b/docs/install/windows.md @@ -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 @@ -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 @@ -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. @@ -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.) @@ -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 @@ -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: . ![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: