Ignore automatically generated directories

[paultcochrane]

When installing the dependencies with cpm I noticed that the local/
directory is created automatically and doesn't need to be checked in to
the repository, hence it can be ignored so that the working directory
remains clean. The same is for the cover_db/ directory which is
created when generating coverage information.

If you would like any changes, please let me know and I'll be happy to update the PR and resubmit as appropriate.

[karenetheridge]

I don't understand what workflow you're using where this happens? cpm should be pulling from a cpan mirror, and those directories don't exist in the cpan release (and I think the dist.ini would exclude them if they happened to be created during a build/release cycle).

[oalders]

If you cpm install from the repo root, it will create a ./local dir and git will show the folder as untracked. Similar issue if you run tests with coverage.

So, it would actually probably prevent dzil from releasing because of the untracked files. I think it makes sense to ignore those dirs by default.

[paultcochrane]

I don't understand what workflow you're using where this happens? cpm should be pulling from a cpan mirror, and those directories don't exist in the cpan release (and I think the dist.ini would exclude them if they happened to be created during a build/release cycle).

I was using the workflow from the GitHub actions config which uses cpm to install the dependencies; I guessed that this was the preferred way to install deps. As @oalders surmised, I ran cpm from the repository's root directory, hence why the local/ dir is generated there.

To generate coverage information I used:

cover -delete
HARNESS_PERL_SWITCHES=-MDevel::Cover prove -lr t xt
cover

Is there a preferred way to build, test and install this dist from the repository? Unfortunately, I couldn't find any docs mentioning how this should be done in the standard case. Would such information be helpful? If so, I could write up my notes and submit them as a PR. Where would be the best place to put such documentation for this project? Perhaps a CONTRIBUTING file?

BTW: I also tried using dzil to install the dependencies and run the tests (I noticed the dzil.ini file and thought I'd try it out :-) ). I noticed some installation issues:

<snip>
! Installing the dependencies failed: Module
'Code::TidyAll::Plugin::SortLines::Naturally' is not installed, Module
'Test::Code::TidyAll' is not installed, Module
'Code::TidyAll::Config::INI::Reader' is not installed, Module
'Code::TidyAll::Plugin::UniqueLines' is not installed
! Bailing out the installation for
Dist-Zilla-PluginBundle-Author-OALDERS-0.000029.

The root cause of this issue seemed to be that the package php-xmlwriter was missing; installing it with

sudo apt install php-xmlwriter

allowed the missing dependencies to be installed on my system. I haven't had a chance to work out what the necessary package would be on a Windows system though. Anyway, I thought this might be useful information in case someone else tries to build the dist directly from the repo source.

[oalders]

Is there a preferred way to build, test and install this dist from the repository?

I usually just use dzil, but people should be able to install the deps in the cpanfile and then just use prove to run the tests. Something like that would be worth documenting.

Not sure what's in php-xmlwriter that satisfies the dependency requirements. 🤔

[oalders]

Thanks, @paultcochrane!

[paultcochrane]

Thanks for merging this @oalders! I'll try and work out where the php-xmlwriter dependency came from exactly. I admit that needing this package sounded ... odd, however I thought I'd document what I came across in the hope that it's helpful somewhere.

Where should information about the preferred way to build and test the dist from a repo clone be documented? Would a CONTRIBUTING.md file be a good idea?

[oalders]

Would a CONTRIBUTING.md file be a good idea?

Yes, I think that would be really helpful!

[paultcochrane]

Not sure what's in php-xmlwriter that satisfies the dependency requirements.

Just so that it's documented somewhere: I've built and tested Net::HTTP within a fresh installation matching my dev box (Debian buster) and didn't run into the issue that the php-xmlwriter package was required. Dunno what was wrong with my system when I was first trying to get Net::HTTP going...

Here's the Dockerfile I used to set up the fresh test system:

FROM debian:buster
# ensure everything is up to date
RUN apt update && apt upgrade -y
# required for basic stuff (perlbrew, repo cloning, ...) to work
RUN apt install -y vim git build-essential curl
# needed for Net::SSLeay, which is needed for Dist::Zilla
RUN apt install -y libssl-dev zlib1g-dev

# create a non-root user for remaining tasks
RUN adduser --disabled-password --gecos "" nethttp
USER nethttp

WORKDIR /home/nethttp
COPY build-net-http.sh build-net-http.sh

Here's the shell script mentioned within the Dockerfile above to set up perlbrew, and build and test Net::HTTP within a Docker container:

#!/bin/bash

# install and set up perlbrew
curl -L https://install.perlbrew.pl | bash

# use bash and source scripts for perlbrew
source ~/perl5/perlbrew/etc/bashrc

perlbrew install-cpanm
perlbrew install -v 5.30.1
perlbrew use 5.30.1

# clone the dist repo
git clone https://github.com/libwww-perl/Net-HTTP.git
cd Net-HTTP

# install prereqs
cpanm --notest Dist::Zilla
dzil authordeps --missing | cpanm
dzil listdeps --missing | cpanm

# required for `dzil test` to work
# cpanm Pod::Coverage::TrustPod Test::Pod::Coverage

# test the dist
dzil test
dzil test --release --author

The commands I used to build and run everything were:

docker build --tag build-test-net-http .
docker run -it build-test-net-http:latest
nethttp@9fcc952c6d8c:~$ ./build-net-http.sh

Hope that helps!

[oalders]

Thanks very much for documenting this @paultcochrane! In case it's helpful at all, you can also find a bunch of Perls with pre-installed dzil at https://registry.hub.docker.com/r/perldocker/perl-tester They should be getting built nightly.