From a36b2669f62e2213e0148babf202cfddf8dc8816 Mon Sep 17 00:00:00 2001 From: Lorenz Neureuter Date: Fri, 30 Jun 2023 23:26:15 -0400 Subject: [PATCH 1/2] docs - Update installation instructions for latest release and advise to use mambaforge --- README.md | 6 +++--- doc/installation.rst | 46 +++++++++++++++++++++++--------------------- 2 files changed, 27 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 46f1eafd9..9c74c54fe 100644 --- a/README.md +++ b/README.md @@ -73,10 +73,10 @@ conda create -n cadquery conda activate cadquery # Install the latest released version -conda install -c conda-forge cadquery occt=7.7.0 +mamba install -c conda-forge cadquery # Or install the dev version to get the latest changes -conda install -c conda-forge -c cadquery cadquery=master +mamba install -c conda-forge -c cadquery cadquery=master ``` ### CadQuery Installation Via Pip @@ -192,7 +192,7 @@ If you are going to contribute code, make sure to follow this steps: - Activate the new conda environment: - `conda activate cq-dev` - If desired, install the master branch of cq-editor (Note; a release version may not be compatible with the master branch of cadquery): - - `conda install -c cadquery -c conda-forge cq-editor=master` + - `mamba install -c cadquery -c conda-forge cq-editor=master` Installing cq-editor adds another instance of cadquery which overrides the clone just added. Fix this by reinstalling cadquery using pip: - `pip install -e .` - Before making any changes verify that the current tests pass. Run `pytest` from the root of your cadquery clone, there should be no failures and the output will look similar to this: diff --git a/doc/installation.rst b/doc/installation.rst index e69a253bd..dcae09d76 100644 --- a/doc/installation.rst +++ b/doc/installation.rst @@ -18,54 +18,57 @@ Begin by installing the conda package manager. If conda is already installed sk Install the Conda Package Manager `````````````````````````````````` -In principle, any Conda distribution will work, but it is probably best to install `Miniforge `_ to a local directory and to avoid running `conda init`. After performing a local directory installation, Miniforge can be activated via the [scripts,bin]/activate scripts. This will help avoid polluting and breaking the local Python installation. +In principle, any Conda distribution will work, but it is probably best to install `Mambaforge `_ to a local directory and to avoid running `conda init`. After performing a local directory installation, Mambaforge can be activated via the [scripts,bin]/activate scripts. This will help avoid polluting and breaking the local Python installation. + +Mambaforge is a minimal installer that sets *conda-forge* as the default channel for package installation and provides **mamba**. ``mamba install`` is recommended over ``conda install`` for faster and less memory intensive caduqery installation. In Linux/MacOS, the local directory installation method looks something like this:: - # Install the script to ~/miniforge - wget https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh -O miniforge.sh - bash miniforge.sh -b -p $HOME/miniforge + # Install to ~/mambaforge + curl -L -o mambaforge.sh "https://github.com/conda-forge/miniforge/releases/latest/download/Mambaforge-$(uname)-$(uname -m).sh" + bash mambaforge.sh -b -p $HOME/mambaforge - # To activate and use Miniconda - source $HOME/miniforge/bin/activate + # Activate + source $HOME/mambaforge/bin/activate On Windows, download the installer and double click it on the file browser or install non-interactively as follows:: - :: Install - curl -L -o miniforge.exe https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Windows-x86_64.exe - start /wait "" miniforge.exe /InstallationType=JustMe /RegisterPython=0 /NoRegistry=1 /NoScripts=1 /S /D=%USERPROFILE%\Miniforge3 + :: Install to %USERPROFILE%\Mambaforge + curl -L -o mambaforge.exe https://github.com/conda-forge/miniforge/releases/latest/download/Mambaforge-Windows-x86_64.exe + start /wait "" mambaforge.exe /InstallationType=JustMe /RegisterPython=0 /NoRegistry=1 /NoScripts=1 /S /D=%USERPROFILE%\Mambaforge :: Activate - cmd /K ""%USERPROFILE%/Miniforge3/Scripts/activate.bat" "%USERPROFILE%/Miniforge3"" + cmd /K ""%USERPROFILE%/Mambaforge/Scripts/activate.bat" "%USERPROFILE%/Mambaforge"" It might be worthwhile to consider using ``/NoScripts=0`` to have an activation shortcut added to the start menu. After conda installation, create and activate a new `conda environment `_ to prepare for cadquery installation. -Note that miniforge automatically sets *conda-forge* as the default channel. ``-c conda-forge`` can be omitted from the install command when using a miniforge installation. - conda ````` -Install the latest released version of cadquery [#f1]_:: +Install the latest released version of cadquery:: - conda create -n cqrel - conda activate cqrel - conda install -c conda-forge cadquery occt=7.7.0 + conda create -n cq + conda activate cq + mamba install cadquery or install a given version of cadquery [#f1]_:: conda create -n cq22 conda activate cq22 - conda install -c conda-forge cadquery=2.2.0 occt=7.7.0 + mamba install cadquery=2.2.0 occt=7.7.0 or install the latest dev version:: conda create -n cqdev conda activate cqdev - conda install -c cadquery -c conda-forge cadquery=master + mamba install -c cadquery cadquery=master + + +Add the *conda-forge* channel explicitly to the install command if needed (not using a miniforge based conda distribution). Install via pip @@ -178,7 +181,7 @@ Example cq-editor installation with conda (this installs both cadquery and cq-ed conda create -n cqdev conda activate cqdev - conda install -c cadquery -c conda-forge cq-editor=master + mamba install -c cadquery cq-editor=master Example cq-editor installation with pip:: @@ -199,7 +202,7 @@ conda .. code-block:: - conda install -c conda-forge jupyterlab + mamba install jupyterlab pip @@ -237,5 +240,4 @@ You should see raw SVG output displayed on the command line if the CadQuery inst .. note:: - .. [#f1] Installation of the latest release (version 2.2.0) with conda requires you to specify the version of the OCCT dependency. - Typically this is not required as the dependencies are managed automatically. + .. [#f1] Older releases may not be compatible with the latest OCCT version. In that case, specify the version of the OCCT dependency explicitly. From 7d9535f3bafc0397599fb3a41c037eb7dba9bf9e Mon Sep 17 00:00:00 2001 From: Lorenz Neureuter Date: Fri, 30 Jun 2023 23:38:57 -0400 Subject: [PATCH 2/2] Typo --- doc/installation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/installation.rst b/doc/installation.rst index dcae09d76..90ee6496b 100644 --- a/doc/installation.rst +++ b/doc/installation.rst @@ -20,7 +20,7 @@ Install the Conda Package Manager In principle, any Conda distribution will work, but it is probably best to install `Mambaforge `_ to a local directory and to avoid running `conda init`. After performing a local directory installation, Mambaforge can be activated via the [scripts,bin]/activate scripts. This will help avoid polluting and breaking the local Python installation. -Mambaforge is a minimal installer that sets *conda-forge* as the default channel for package installation and provides **mamba**. ``mamba install`` is recommended over ``conda install`` for faster and less memory intensive caduqery installation. +Mambaforge is a minimal installer that sets *conda-forge* as the default channel for package installation and provides **mamba**. ``mamba install`` is recommended over ``conda install`` for faster and less memory intensive cadquery installation. In Linux/MacOS, the local directory installation method looks something like this::