From 688ab37f7b36cb4a33651038da570230cda2a712 Mon Sep 17 00:00:00 2001 From: Adam Clark Date: Fri, 26 Jul 2024 12:59:42 -0700 Subject: [PATCH] Rewrote the installation page --- Installation.md | 94 ++++++++++++++++++++++++++----------------------- PyInstaller.md | 33 ----------------- README.md | 14 ++++---- Support.md | 6 ++++ 4 files changed, 63 insertions(+), 84 deletions(-) delete mode 100644 PyInstaller.md diff --git a/Installation.md b/Installation.md index 5e1ca88..4878de8 100644 --- a/Installation.md +++ b/Installation.md @@ -1,69 +1,46 @@ # PyWEED Installation -PyWEED is distributed as an [anaconda](https://conda.io/docs/) package. +**Not compatible with Python 3.12** +Currently (2024-07-26) PyWEED cannot run under Python 3.12, due to unavailable dependencies. -Some troubleshooting information can be found in [Support](Support.md). - -## Install Anaconda/Miniconda (if needed) - -This is the conda package manager. Miniconda is a lighter version of Anaconda, and is recommended. - -__[Miniconda Installers](https://conda.io/miniconda.html)__ - -This page includes both 2.x and 3.x versions, it's better to get the 3.x version. (It doesn't strictly matter, though.) - -__Mac/Linux__: the installation process should put the `conda` command in your shell `PATH`. -__Windows__: launch the Anaconda Prompt application installed by Miniconda for the next steps. - -## Install PyWEED - -Run the following command: +PyWEED is most reliably installed using [conda](https://conda.io/docs/): ``` -conda create -n pyweed -c conda-forge python=3 pyweed +conda install -c conda-forge pyweed ``` -This creates a `pyweed` [environment](https://conda.io/docs/using/envs.html) in Anaconda, and installs Python 3, PyWEED, -and all associated dependencies from [conda-forge](https://github.com/conda-forge/) into that environment. - -# Running PyWEED - -__Mac/Linux__ +For best results, create a dedicated environment: ``` -conda activate pyweed -pyweed +conda create -n pyweed -c conda-forge pyweed ``` -__Windows__ (from the Anaconda Prompt) +It can also be installed via pip, although you may need system libraries for some dependencies: ``` -activate pyweed -pyweed +pip install pyweed ``` -# Other Options - -## Network Install +Some troubleshooting information can be found in [Support](Support.md). -__Mac/Linux only__ +## Running PyWEED -This command should perform a complete installation: +PyWEED installs a `pyweed` script, so from the command line: ``` -bash <(curl -Ss https://raw.githubusercontent.com/iris-edu/pyweed/master/installer/install.sh) +pyweed ``` -This downloads and runs a script that essentially performs the steps outlined above. +## Other installation topics -## Clickable Application +### Clickable Application -__Mac/Windows only__ +**Mac/Windows only** This produces a small application that will launch PyWEED when clicked, suitable for adding to your Desktop or launch bar. -__Mac__ +**Mac** ``` conda activate pyweed @@ -71,7 +48,7 @@ pyweed_build_launcher mv PyWEED.app /Applications/ ``` -__Windows__ +**Windows** ``` activate pyweed @@ -79,7 +56,39 @@ pyweed_build_launcher move PyWEED.bat Desktop ``` -## Source Code +### Installing Anaconda/Miniconda + +This is the conda package manager. Miniconda is a lighter version of Anaconda, and is recommended. + +**[Miniconda Installers](https://conda.io/miniconda.html)** + +(PyWEED requires **Python 3.11** or below!) + +**Mac/Linux**: the installation process should put the `conda` command in your shell `PATH`. +**Windows**: launch the Anaconda Prompt application installed by Miniconda for the next steps. + +You can + +``` +conda create -n pyweed -c conda-forge pyweed +``` + +This creates a `pyweed` [environment](https://conda.io/docs/using/envs.html) in Anaconda, and installs Python 3, PyWEED, +and all associated dependencies from [conda-forge](https://github.com/conda-forge/) into that environment. + +### Network Install + +**Mac/Linux only** + +This command should perform a complete installation: + +``` +bash <(curl -Ss https://raw.githubusercontent.com/iris-edu/pyweed/master/installer/install.sh) +``` + +This downloads and runs a script that builds a conda environment and installs PyWEED into it. Note that this may auto-install various dependencies. + +### Source Code Clone the PyWEED repository with: @@ -90,9 +99,6 @@ git clone https://github.com/iris-edu/pyweed.git or [download as a zip file](https://github.com/iris-edu/pyweed/archive/master.zip) and unzip into a `pyweed` directory. ``` -conda activate pyweed cd pyweed python run_pyweed.py ``` - - diff --git a/PyInstaller.md b/PyInstaller.md deleted file mode 100644 index e910c72..0000000 --- a/PyInstaller.md +++ /dev/null @@ -1,33 +0,0 @@ -# PyInstaller - -__Obsolete!__ This page documents a path that was eventually abandoned - -Distributable binaries are built with PyInstaller. This isn't included in the normal environment, so you need to -install it. It's also not available through Anaconda so you need to install it with pip: - -``` -pip install pyinstaller -``` - -To create a binary: - -``` -cd installer -pyinstaller pyweed_gui.spec -``` - -The binary will be under `installer/dist/pyweed_gui`. - -## Mac Binary - -To create a Mac `.app` binary, set `ONE_FILE = True` in `pyweed_gui.spec`. This should build the app alongside -the other build products. - -To distribute, create a DMG file which the user can mount as its own filesystem, here is a simple version: - - mkdir /tmp/PyWEED - cp -R installer/dist/PyWEED.app /tmp/PyWEED - ln -s /Applications /tmp/PyWEED - hdiutil create /tmp/PyWEED.dmg -srcfolder /tmp/PyWEED -volname "PyWEED" - - diff --git a/README.md b/README.md index 0eb7e6b..e1ce353 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,11 @@ ## About PyWEED +**[Installation Guide](Installation.md)** + +**[User Guide](UserGuide/index.md)** + +**[Support](Support.md)** + PyWEED is an application for retrieving event-based seismic data. PyWEED works on Windows, Mac, and Linux (64-bit). It is built on [ObsPy](https://obspy.org/) and @@ -9,16 +15,10 @@ PyWEED works on Windows, Mac, and Linux (64-bit). It is built on [ObsPy](https:/ ![Waveforms Window](WaveformsWindow.png) -[Demo Screencast](https://vimeo.com/246357529) on Vimeo +[Demo Screencast](https://vimeo.com/246357529) on Vimeo ## Documentation -__[Installation Guide](Installation.md)__ - -__[User Guide](UserGuide/index.md)__ - -__[Support](Support.md)__ - Please send comments/problems to [data-help@earthscope.org](data-help@earthscope.org). --- diff --git a/Support.md b/Support.md index f0c2445..bcbc257 100644 --- a/Support.md +++ b/Support.md @@ -1,5 +1,9 @@ # Support +## PyWEED crashes on startup + +The most common reason is a problem in the configuration file. This is located at `~/.pyweed/pyweed.ini`. If you move or delete it, PyWEED will recreate a fresh version the next time it starts. + ## Install problems Far and away the most common problem is library mismatches -- some of the libraries that PyWEED uses (ObsPy and Qt most notably) bring in a wide mix of their own dependencies, resulting in a complex mix of library versions. @@ -11,9 +15,11 @@ This can be addressed by specifying PyWEED's direct dependencies in more granula #### ImportError: cannot import name 'dedent' from 'matplotlib.cbook' See [#119](https://github.com/iris-edu/pyweed/issues/119) -- in an existing environment running + ``` conda install matplotlib=3.2 ``` + should install the correct package. ## Contact