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 and packaging documentation #311

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
74 changes: 42 additions & 32 deletions perl/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ To build a docker image using the `Dockerfile`, run the following:
docker build --tag bystro-cli .
```

## Installing Bystro using `cpam`
## Installing Bystro using `cpanm`

The instructions for installing Bystro locally uses [`cpanm`](https://metacpan.org/pod/App::cpanminus).

Expand All @@ -19,16 +19,23 @@ But there are a few one-off dependencies that require a slightly modified approa
One-off dependencies can be installed as follows:

```bash
# install msgpack fork
cpanm --quiet https://github.com/bystrogenomics/msgpack-perl.git

# install MouseX::Getopt despite some tests failing
cpanm --quiet --notest MouseX::Getopt

# install LMDB_File that comes with latest LMDB
git clone --depth 1 --recurse-submodules https://github.com/salortiz/LMDB_File.git \
&& cd LMDB_File \
&& cpanm --quiet . \
&& cd .. \
&& rm -rf LMDB_File

# install mysql driver
# NOTE: you will need mysql_config to install this
# ubuntu 22.04 LTS => sudo apt install -y libmariadb-dev libmariadb-dev-compat
# amazon 2023 => sudo yum install -y <mariadb105>
# amazon 2023 => sudo yum install -y mariadb105-devel.x86_64
cpanm --quiet DBD::mysql@4.051
```

Expand All @@ -38,59 +45,62 @@ The remaining dependencies are installed like this:
cpanm --installdeps .
```

After installing dependencies, use `prove -lr t` to run tests.

## Installing Bystro locally using dzil

Bystro uses [`Dist::Zilla`](https://github.com/rjbs/dist-zilla) for packaging and is configured with `dist.ini`.
This approach requires installing `Dist::Zilla` and author dependencies and one off-dependencies described in the above.

```bash
# Install Dist::Zilla and Archive::Tar::Wrapper (to slightly speed up building)
cpanm --quiet Dist::Zilla Archive::Tar::Wrapper

# Install build dependencies
dzil authordeps --missing | cpanm --quiet

# Install Bystro dependencies
dzil listdeps --missing | cpanm --quiet

# Install Bystro
dzil install
```

## Install Bystro using `cpm`

Install [cpm](https://metacpan.org/pod/App::cpm) with `curl -fsSL https://raw.githubusercontent.com/skaji/cpm/main/cpm | perl - install -g App::cpm`.

```bash
# install msgpack fork
cpm https://github.com/bystrogenomics/msgpack-perl.git
cpm install -g https://github.com/bystrogenomics/msgpack-perl.git
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we use cpm here and cpanm above; could we go to cpm throughout? I have a change I can make the corresponding change to the perlbrew script

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The problem with using cpm throughout is that cpanm is needed for installing LMDB_File - at least I couldn't find a way of using it. If your concern is that it is confusing to have two sections - one for cpamn and one for cpm - then I suggest consolidation of the two approaches with the acknowledgement that both tools are needed.


# install MouseX::Getopt despite some tests failing
cpm --no-test MouseX::Getopt
cpm install -g --no-test MouseX::Getopt

# install LMDB_File that comes with latest LMDB
# NOTE: you will need mysql_config to install this
# ubuntu 22.04 LTS => sudo apt install -y libmariadb-dev libmariadb-dev-compat
# amazon 2023 => sudo yum install -y <mariadb105>
git clone --depth 1 --recurse-submodules https://github.com/salortiz/LMDB_File.git \
&& cd LMDB_File \
&& cpanm . \
&& cd .. \
&& rm -rf LMDB_File

# install mysql driver
cpm DBD::mysql@4.051
# NOTE: you will need mysql_config to install this
# ubuntu 22.04 LTS => sudo apt install -y libmariadb-dev libmariadb-dev-compat
# amazon 2023 => sudo yum install -y mariadb105-devel.x86_64
cpm install -g DBD::mysql@4.051

# clone bystro and change into perl package
git clone git@github.com:bystrogenomics/bystro.git && cd bystro/perl

# install dependencies
# install dependencies (uses cpanfile)
cpm install -g --with-develop
```

After installing dependencies, use `prove -lr t` to run tests.

## Installing development tools

These are tools needed for packaging and releasing Bystro's Perl package, which are not needed for normal testing or development.

Bystro uses [`Dist::Zilla`](https://github.com/rjbs/dist-zilla) for packaging and is configured with `dist.ini`.
This approach requires installing `Dist::Zilla` and author dependencies and one off-dependencies described in the above.

```bash
# Install Dist::Zilla and Archive::Tar::Wrapper (to slightly speed up building)
cpanm --quiet Dist::Zilla Archive::Tar::Wrapper
# - or -
cpm install -g Dist::Zilla Archive::Tar::Wrapper

# Install build dependencies
dzil authordeps --missing | cpanm --quiet
# - or -
cpm install -g $(dzil authordeps --missing)

# Install Bystro Package
dzil install

# Install dzil build dependencies
RUN cpm install -g --show-build-log-on-failure $(dzil authordeps --missing)
# Test Bystro Package
dzil test --all
```

## Coding style and tidying
Expand Down