Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update installation docs to remove briefcase bundle mentions #147

Merged
merged 15 commits into from
May 30, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 7 additions & 18 deletions docs/developers/packaging.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,24 +70,14 @@ A software installer is usually expected to fulfill these requirements:
* It will provide a convenient way of opening the application, like a shortcut or a menu entry.
* It will allow the user to uninstall the application, leaving no artifacts behind.

Right now, we are using two ways of generating the installers:

* With `briefcase`, which takes PyPI packages.
* With `constructor`, which takes `conda` packages.

We use `constructor` to build the bundled installers, which takes `conda` packages.
`conda` packages offer several advantages when it comes to bundling dependencies, since it makes very few assumptions about the underlying system installation.
As a result, `constructor` bundles include libraries that might be missing in the target system and hence should provide a more robust user experience.

### Briefcase-based installers

[`briefcase`][5] based installers are marked for deprecation, so we will not discuss them here.
If you are curious, you can check `bundle.py` and `.github/workflows/make_bundle.yml` for details.

### Constructor-based installers

We use `constructor` to build the `napari` installers through the `.github/workflows/make_bundle_conda.yml` workflow,
which only specifies the triggers used to call the actual workflow implementation under the `napari/packaging` repository.
This repository stores all the logic and files needed to create the nightly `conda` packages and the `constructor` installers.
The automation is implemented in the `.github/workflows/make_bundle_conda.yml` workflow, which only
specifies the triggers used to call the actual workflow implementation under the `napari/packaging`
repository. This repository stores all the logic and files needed to create the nightly `conda`
packages and the `constructor` installers.

[`constructor`][6] allows you to build cross-platform installers out of `conda` packages.
It supports the following installer types:
Expand All @@ -110,7 +100,7 @@ company: Napari
license: EULA.md
channels:
# - local # only in certain situations, like nightly installers where we build napari locally
- napari/label/bundle_tools # temporary location of our forks of the constructor stack
- napari/label/bundle_tools_2 # temporary location of our forks of the constructor stack
- conda-forge
specs: # specs for the 'base' environment
- python # pinned to the version of the running interpreter, configured in the CI
Expand Down Expand Up @@ -156,7 +146,7 @@ The main OS-agnostic keys are:

* `channels`: where the packages will be downloaded from.
We mainly rely on `conda-forge` for this, where `napari` is published.
However, we also have `napari/label/bundle_tools`, where we store our `constructor` stack forks (more on this later).
However, we also have `napari/label/bundle_tools_2`, where we store our `constructor` stack forks (more on this later).
In nightly installers, we locally build our own development packages for `conda`, without resorting to `conda-forge`.
To make use of those (which are eventually published to `napari/label/nightly`),
we unpack the GitHub Actions artifact in a specific location that `constructor` recognizes as a _local_ channel once indexed.
Expand Down Expand Up @@ -323,7 +313,6 @@ a high-level list of the main changes introduced in the stack.
[2]: https://github.com/napari/napari/blob/main/.github/workflows/make_release.yml
[3]: https://github.com/napari/napari/blob/main/Makefile#L20
[4]: https://github.com/pypa/gh-action-pypi-publish
[5]: https://github.com/beeware/briefcase
[6]: https://github.com/conda/constructor
[7]: https://github.com/conda/constructor/blob/main/CONSTRUCT.md
[8]: https://conda-forge.org/docs/maintainer/updating_pkgs.html#rerendering-feedstocks
Expand Down
Binary file not shown.
Binary file not shown.
Binary file not shown.
99 changes: 9 additions & 90 deletions docs/tutorials/fundamentals/installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,12 +46,6 @@ You may also want:
This is the easiest way to install napari if you only wish to use it as a standalone GUI app.
This installation method does not have any prerequisites.

```{important}
Note that the bundled app is still
in active development, and may not be very stable. We strongly recommend
[installing as a Python package instead](#install-as-python-package-recommended).
```

psobolewskiPhD marked this conversation as resolved.
Show resolved Hide resolved
[Click here](#install-as-a-bundled-app) to see instructions
for installing the bundled app.

Expand Down Expand Up @@ -218,102 +212,27 @@ you're not using.
## Install as a bundled app

napari can also be installed as a bundled app on each of the major platforms,
MacOS, Windows, and Linux with a simple one click download and installation
MacOS, Windows, and Linux with a simple one-click download and installation
process. You might want to install napari as a bundled app if you are unfamiliar
with installing Python packages or if you were unable to get the installation
process described above working. The bundled app version of napari is the same
version that you can get through the above described processes, and can still be
extended with napari plugins installed directly via the app.

```{important}
Note that the bundled app is still
in active development, and may not be very stable. We strongly recommend
[installing as a Python package instead](#install-as-python-package-recommended).
```

To access the cross platform bundles you can visit our [release
page](https://github.com/napari/napari/releases) and scroll to the release you
are interested in. For example, the bundles for napari {{ napari_version }} can be
accessed {{ '[here](https://github.com/napari/napari/releases/tag/vNAPARI_VER)'.replace('NAPARI_VER', napari_version) }}.
To get to the download link, just scroll all the way to bottom of the page and
expand the `Assets` section to get a view that looks like this:

![Cropped screenshot from GitHub with the Assets section (or "tab") expanded, containing links to download the app in the form of zip files for Linux, macOS, Windows, in addition to other links.](../assets/tutorials/installation/bundle_assets.png)

You can then download the appropriate zip file for your platform.

### Installing the MacOS bundle

Once you have downloaded the MacOS bundle zip you will have a zip file with a
name like `napari-0.3.7-macOS.zip`. After unzipping you will have a file with a
name like `napari-0.3.7.dmg`. Double clicking the `dmg` will open a new finder
window giving you the option to install napari into your `Applications` folder
by dragging the `napari` icon onto the `Applications` icon.

![Finder window of the napari bundle dmg file, containing the napari app icon and a shortcut icon to the Applications folder.](../assets/tutorials/installation/bundle_install.png)

After you drag the `napari` icon onto the `Applications` icon napari will be
installed in your Applications folder and available for opening by double
clicking on it.

![Finder window of the Applications folder containing the napari app.](../assets/tutorials/installation/bundle_applications_folder.png)

The first time you try and open napari you will get the "unverified developer
warning" that appears below:

![Finder pop up with the warning "napari cannot be opened because the developer cannot be verified" and the options "Move to Trash" or "Cancel."](../assets/tutorials/installation/bundle_dev_warning.png)

Don't be alarmed, this is because the napari team has not yet obtained a
developer certificate from Apple, but we will be doing this promptly. It is safe
to click "Cancel". To get napari to open you must enter "Systems Preferences"
and click the "Security & Privacy" icon, circled in red below:

![MacOS System Preferences with the Security & Privacy settings on the far right of the second row.](../assets/tutorials/installation/bundle_security_privacy.png)

Once inside the "Security & Privacy" tab, you should see a message about napari
being blocked and an "Open Anyway" button, circled in red below:

![System Preferences Security & Privacy section's General tab. At the bottom of the window there is a notification that napari was blocked and the button to "Open Anyway."](../assets/tutorials/installation/bundle_open_anyway.png)

After clicking this button you'll get one final warning about napari not being
verified, but now you'll have an "Open" button, as seen below:

![Finder pop up with the warning "macOS cannot verify the developer of napari. Are you sure you want to open it?" and the options "Move to Trash," "Open," or "Cancel."](../assets/tutorials/installation/bundle_open.png)

After clicking "Open", the viewer should appear. Don't worry, you only have to
go through this process once when you install a new bundle.

### Installing the Windows bundle

Once you have downloaded the Windows bundle zip you will have a zip file with a
name like `napari-0.3.7-Windows.zip`. Unzip the bundle (you may like to use a
tool like [7-zip](https://www.7-zip.org/) for this) and double click on msi
file, eg: `napari-0.3.7.msi`

The napari setup wizard will then open. Click "Next" to begin the installation.

![napari Setup window with a welcome message and button to continue with "Next."](../assets/tutorials/installation/windows_bundle_installer_start.png)

![napari Setup window in the process of installing napari. The progress bar has a Status that describes which step is in progress.](../assets/tutorials/installation/windows_bundle_installer_progress.png)

After the setup wizard has installed napari, click "Finish" to exit.

![napari Setup window success message with the button to "Finish" installation.](../assets/tutorials/installation/windows_bundle_installer_finish.png)

When you launch the bundled napari app on Windows, first you'll see an empty
command terminal appear (do not close this window - you can ignore it). The
command terminal will be followed by a napari splash screen, and then the main
napari user interface window will appear a few seconds later. Note that errors
which might occur during your napari session will appear on the command terminal -
so if something is not working, it might pay to take a look at the terminal!

![Windows command terminal on napari launch.](../assets/tutorials/installation/windows_bundle_command_terminal.png)

You can launch napari from the Windows start menu.

![Windows start menu with napari listed as a launchable app.](../assets/tutorials/installation/windows_launch_napari.png)

The very first time you launch napari the startup time will be fairly slow, but
after that you will find that napari launches more quickly.
expand the `Assets` section. You can then download the appropriate file for your platform.

### Installing the Linux bundle

(Guide coming soon... In the meantime, if you try it and encounter issues, see
below for how to contact us.)
<!-- #endregion -->

## Next steps
Expand All @@ -325,7 +244,7 @@ contributing to napari please check our [contributing
guidelines](../../developers/contributing.md)
- if you are running into issues or bugs, please open a new issue on our [issue
tracker](https://github.com/napari/napari/issues)
- include the output of `napari -info`
- include the output of `napari --info`
(or go to `Help>Info` in the viewer and copy paste the information)
- if you want help using napari, we are a community partner on the [imagesc
forum](https://forum.image.sc/tags/napari) and all usage support requests should
Expand Down
15 changes: 7 additions & 8 deletions docs/tutorials/fundamentals/quick_start.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,13 +48,12 @@ You will also see some examples of plugins. The core napari viewer focuses on do

### Installation

- Download the napari {{ napari_version }} bundled app for simple installation:

{{ '[Linux installation](https://github.com/napari/napari/releases/download/vNAPARI_VER/napari-NAPARI_VER-Linux-x86_64.zip)'.replace('NAPARI_VER', napari_version) }}<br>
{{ '[macOS installation](https://github.com/napari/napari/releases/download/vNAPARI_VER/napari-NAPARI_VER-macOS-x86_64.zip)'.replace('NAPARI_VER', napari_version) }}<br>
{{ '[Windows installation](https://github.com/napari/napari/releases/download/vNAPARI_VER/napari-NAPARI_VER-Windows-x86_64.zip)'.replace('NAPARI_VER', napari_version) }}<br>

*Note: for all other releases, please visit [here](https://github.com/napari/napari/releases) and look for Assets.*
- Download the napari {{ napari_version }} bundled app for a simple installation:
- Linux: {{ '[`napari-NAPARI_VER-Linux-x86_64.sh`](https://github.com/napari/napari/releases/download/vNAPARI_VER/napari-NAPARI_VER-Linux-x86_64.sh)'.replace('NAPARI_VER', napari_version) }}.
- macOS (Intel): {{ '[`napari-NAPARI_VER-macOS-x86_64.pkg`](https://github.com/napari/napari/releases/download/vNAPARI_VER/napari-NAPARI_VER-macOS-x86_64.pkg)'.replace('NAPARI_VER', napari_version) }}.
- macOS (Apple Silicon): {{ '[`napari-NAPARI_VER-macOS-arm64.pkg`](https://github.com/napari/napari/releases/download/vNAPARI_VER/napari-NAPARI_VER-macOS-arm64.pkg)'.replace('NAPARI_VER', napari_version) }}.
- Windows: {{ '[`napari-NAPARI_VER-Windows-x86_64.exe`](https://github.com/napari/napari/releases/download/vNAPARI_VER/napari-NAPARI_VER-Windows-x86_64.exe)'.replace('NAPARI_VER', napari_version) }}.
- Other artifacts can be found in the {{ '[the Releases page](https://github.com/napari/napari/releases/vNAPARI_VER)'.replace('NAPARI_VER', napari_version) }}, by the Assets section at the bottom.

- For those familiar with Python:

Expand Down Expand Up @@ -91,7 +90,7 @@ napari
- If you installed the bundled app:

Click on the app icon to open it.<br>
*Note: for mac users, it may require [security setting changes](https://napari.org/tutorials/fundamentals/installation.html).*
*Note: macOS users might need to right click on the app icon and select "Open" to bypass the security check. You can also go to System Settings > Privacy & Security and click on "Open Anyway".*

+++

Expand Down