Installation and environment

Problem	Cause and fix
Environment creation fails	conda update -n base conda, then retry ./PoolSeqFlow install
nothing provides __glibc >=N	Your machine's glibc is older than this release's floor of 2.28. ldd --version prints what you have; the floor and why it exists are under The glibc floor. There is no flag for it: use a newer machine
Missing dependencies after install	Activate it: conda activate PoolSeqFlow
A tool is found but misbehaves	Check whether params.software.* points at a system binary rather than the environment's; version mismatches are not detected

Why Linux only

Windows. The pipeline moves each file it produces to where it belongs and leaves a symbolic link behind, and it relies on Unix path semantics throughout. Neither behaves correctly on native Windows filesystems, and WSL only works under some filesystem configurations, which is not a guarantee worth documenting. See Symbolic links and the two storage roots.

macOS. Every tool a release runs is pinned to an exact build in install/environment.yml and install/environment-analysis.yml, and those files are exports from a Linux machine: they name builds that exist for linux-64 and for no other platform. Conda cannot solve either of them on a Mac, so the install fails before anything else is reached. Supporting macOS means a second set of pinned files exported and verified on a Mac (one for Apple Silicon and one for Intel, since conda treats them as different platforms), and that is a piece of work rather than a flag. Earlier releases listed macOS as supported; that was never true of the pinned environments, and saying so was the error.

The glibc floor

The floor is glibc 2.28, and it applies to both environments. In distribution terms that is RHEL and Rocky 8, Debian 10, Ubuntu 18.10, and everything released after them. The one common machine it excludes is CentOS 7, which reached end of life in June 2024.

__glibc is conda's name for the glibc your machine has, and ldd --version prints it. Below the floor, conda refuses the solve rather than installing something that would fail later, and the message names a virtual package instead of a distribution:

LibMambaUnsatisfiableError: Encountered problems while solving:
  - nothing provides __glibc >=2.28 needed by rsync-3.4.4-hffd6c76_1

No flag works around it. Conda offers one that forces the solve, and using it would install binaries the system cannot run, turning a refusal you get in seconds into a crash you get hours into a run. If your machine is below the floor, use a newer one.

What sets it is rsync, which both environments carry. Every artifact the pipeline produces is moved to permanent storage by a copy that is verified before the original is removed, and rsync is what stages that copy. So the floor is a property of the whole release rather than of the analysis layer: the analysis environment additionally carries a C and C++ compiler, because every module builds its hot path on your machine rather than shipping a binary, but that toolchain reaches back further than rsync does and is not what decides this.

Coming from 2.2.0

3.0 was a structural release rather than a handful of new settings. Upgrading is the procedure; this is what changed under it.

What changed	What to do
One storage root became two, and they must be different paths: mainDir holds your reads, reference and configuration and is where you run; storageDir holds finished results	migrate_config prints the mv commands for the files that move
projectDir is now storageDir, because projectDir is a name Nextflow defines for itself	A straight rename; your value is carried over
RGTags.csv is replaced by metadata.csv. The old file held raw SAM read-group tags and nothing else; the new one has seven kinds of column, carries your pool sizes, and gives the experiment itself (populations, timepoints, replicates) somewhere to live	Not a rename, and not migratable: rgTagsFile is reported as no longer used and rewriting the file is yours to do. Start from $POOLSEQFLOW_HOME/metadata.csv.template, which documents every column, and read Metadata. No run starts until metadata.csv exists, so it cannot be deferred
The depth ceiling moved. bcftools.maxDepth = 2000 was the only depth control there was, one number for every pileup in the run. A ceiling is now measured for each sample from its own depth histogram and applied to the BAM before calling (Depth capping), and variantCall.maxDepth is a second ceiling on top of it, shipping as 0, which mpileup reads as no limit at all	Your old value is deliberately not carried: it would cap you at a number this release never chose, on top of a per-sample cap that cannot see it. It is reported under Format changed this release. Automatic capping is capBAM.maxDepth = -1, which is what you now have. To reproduce 2.2.0 results exactly, set variantCall.maxDepth back to your old value and capBAM.maxDepth = 0
The installation is separate from your project. Earlier releases ran from the folder you unpacked, with parameters.config beside the pipeline	Install once, and run the installed command from your own project directory. If your project is the old unpacked folder, move it out: the pipeline refuses to run inside its own installation
Some parameters are gone: params.gff, params.dir.scripts, params.dir.output.temp, rgTagsFile and rgTagsPath	Each is reported under No longer used. The cores block and the options strings look gone and are not: they are computed now and ship commented out, under Still yours to set
Multi-run is new, and off	multiRun = false changes nothing about how an existing project behaves