diff --git a/book/_toc.yml b/book/_toc.yml index 4b56ae0..4472b0d 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -26,6 +26,7 @@ parts: - file: plugins/tutorials/create/plugin - file: plugins/how-to-guides/intro sections: + - file: plugins/how-to-guides/set-up-development-environment - file: plugins/how-to-guides/add-citation - file: plugins/how-to-guides/usage-example - file: plugins/how-to-guides/type-map diff --git a/book/plugins/explainers/intro.md b/book/plugins/explainers/intro.md index e98cd7e..b2e09c7 100644 --- a/book/plugins/explainers/intro.md +++ b/book/plugins/explainers/intro.md @@ -1 +1,2 @@ -# Explainers +(start-plugin-explainers)= +# Explainers: Building a QIIME 2 Plugin diff --git a/book/plugins/how-to-guides/set-up-development-environment.md b/book/plugins/how-to-guides/set-up-development-environment.md new file mode 100644 index 0000000..c1ffece --- /dev/null +++ b/book/plugins/how-to-guides/set-up-development-environment.md @@ -0,0 +1,162 @@ + +# Set up your development environment + +This how-to guide describes how to install and set up a QIIME 2 development environment. +The development environment you create will be suitable for creating new or contributing to existing QIIME 2 plugins or interfaces, or contributing to the development of the QIIME 2 framework. + +```{warning} +QIIME 2 support for Windows is restricted to Windows Subsystem for Linux (WSL). +The QIIME 2 development team doesn't have much experience developing QIIME 2 in the context of Windows. +If you're comfortable with creating development environments with WSL, we expect that it should work just fine. +If you expect that you might need help setting up your development environment, we'll be able to provide better assitance if you're developing on a Linux or macOS system. +``` + +## Install Prerequisites + +{{ miniconda_url }} provides the ``conda`` environment and package manager, and is currently the only supported way to install QIIME 2. +Follow the instructions for downloading and installing Miniconda. + +After installing Miniconda and opening a new terminal, make sure you're running the latest version of ``conda`` (and get a copy of ``wget``, while you're at it): + +```bash +conda update conda +conda install wget +``` + +## Install the latest development version of the QIIME 2 "Tiny Distribution" + +The QIIME 2 "Tiny Distribution" is a minimal set of QIIME 2 functionality for building and using plugins through the QIIME 2 command line, and is intended for use by developers who want a minimal QIIME 2 environment to work in. + +```{note} +We recommend starting your development with the "Tiny Distribution", unless you specifically need plugins that are installed in other QIIME 2 distributions, such as the "Amplicon" or "Shotgun" distributions, in which case see [](other-distros). +``` + +`````{tab-set} +````{tab-item} macOS +```bash +wget https://raw.githubusercontent.com/qiime2/distributions/dev/latest/passed/qiime2-tiny-macos-latest-conda.yml +conda env create -n q2dev-tiny --file qiime2-tiny-macos-latest-conda.yml +rm qiime2-tiny-macos-latest-conda.yml +``` +```` + +````{tab-item} Linux +```bash +wget https://raw.githubusercontent.com/qiime2/distributions/dev/latest/passed/qiime2-tiny-ubuntu-latest-conda.yml +conda env create -n q2dev-tiny --file qiime2-tiny-ubuntu-latest-conda.yml +rm qiime2-tiny-ubuntu-latest-conda.yml +``` +```` +````` + +## Activate the ``conda`` environment + +You can now activate the environment you just created as follows. + +```bash +conda activate q2dev-tiny +``` + +To test your QIIME 2 environment, run: + +```bash +qiime info +``` + +You should see something like the following, though the version numbers you'll see will be different: + +``` +System versions +Python version: 3.8.18 +QIIME 2 release: 2023.11 +QIIME 2 version: 2023.11.0.dev0+15.g8ac7e3e +q2cli version: 2023.11.0.dev0+12.g7cf7a7a + +Installed plugins +types: 2023.11.0.dev0+2.g1827eab + +Application config directory +/Users/gregcaporaso/miniconda3/envs/q2dev-tiny/var/q2cli + +Getting help +To get help with QIIME 2, visit https://qiime2.org +``` + +The versions listed here, for QIIME 2, q2cli, and q2-types, are development versions as defined by [versioneer](https://github.com/python-versioneer/python-versioneer), and these indicate that you're working in a QIIME 2 development environment (as opposed to working with a specific release version of QIIME 2). + +At this stage you should now have a working development environment - time to start hacking! + +## Next steps + +### Building a new plugin + +If you're creating a new plugin, you can now move on to [](start-plugin-tutorial) or [](start-plugin-explainers), depending on whether you'd like to start with step-by-step instructions, or a narrative overview of how QIIME 2 plugins work (respectively). + +### Contributing to existing plugins +If you want to make changes to the QIIME 2 framework, q2cli, or any existing plugins, follow these steps (for the sake of this example, we will focus on the example of contributing to developing ``q2-types``): + +```bash +# Grab the package source from the relevant source repository. +git clone https://github.com/qiime2/q2-types +cd q2-types + +# Install any additional build-time dependencies needed for this project. +# Check ci/recipe/meta.yaml in any QIIME 2 repository under the QIIME 2 GitHub +# organization for build or test requirements. For example, see +# https://github.com/qiime2/q2-types/blob/dev/ci/recipe/meta.yaml +conda install pytest flake8 + +# Install local source in "development mode", and build any package assets. +make dev + +# Run package tests to ensure that everything is okay. +make test +``` + +(other-distros)= +## Installing other QIIME 2 distributions + +```{note} +If you install a distribution other than the "Tiny Distribution", be sure that the environment name in your `conda activate` command (in the example above this was `q2dev-tiny`) matches the value that you provided to the `conda env create` command through the `-n` parameter. +``` + +### Amplicon distribution + +`````{tab-set} +````{tab-item} macOS +```bash +wget https://raw.githubusercontent.com/qiime2/distributions/dev/latest/passed/qiime2-amplicon-macos-latest-conda.yml +conda env create -n q2dev-amplicon --file qiime2-amplicon-macos-latest-conda.yml +rm qiime2-amplicon-macos-latest-conda.yml +``` +```` + +````{tab-item} Linux +```bash +wget https://raw.githubusercontent.com/qiime2/distributions/dev/latest/passed/qiime2-amplicon-ubuntu-latest-conda.yml +conda env create -n q2dev-amplicon --file qiime2-amplicon-ubuntu-latest-conda.yml +rm qiime2-amplicon-ubuntu-latest-conda.yml +``` +```` +````` + +### Shotgun distribution + +`````{tab-set} +````{tab-item} macOS +```bash +wget https://raw.githubusercontent.com/qiime2/distributions/dev/latest/passed/qiime2-shotgun-macos-latest-conda.yml +conda env create -n q2dev-shotgun --file qiime2-shotgun-macos-latest-conda.yml +rm qiime2-shotgun-macos-latest-conda.yml +``` +```` + +````{tab-item} Linux +```bash +wget https://raw.githubusercontent.com/qiime2/distributions/dev/latest/passed/qiime2-shotgun-ubuntu-latest-conda.yml +conda env create -n q2dev-shotgun --file qiime2-shotgun-ubuntu-latest-conda.yml +rm qiime2-shotgun-ubuntu-latest-conda.yml +``` +```` +````` + diff --git a/book/plugins/tutorials/intro.md b/book/plugins/tutorials/intro.md index 678ccd7..eba050f 100644 --- a/book/plugins/tutorials/intro.md +++ b/book/plugins/tutorials/intro.md @@ -1,5 +1,5 @@ -# Tutorials - +(start-plugin-tutorial)= +# Tutorials: Developing a QIIME 2 Plugin ```{tableofcontents} ``` \ No newline at end of file