Developer Resources | Squid Web Cache wiki

Developer Resources | Squid Web Cache wiki
Developer Resources
Contributing code
The best way to contribute code is to submit a high-quality
pull request
against the master
branch of the official
repository
on GitHub. To speed
up code review and improve your code acceptance chances, please adhere
to the
SquidCodingGuidelines
and follow the
MergeProcedure
The
ProgrammingGuide
provides a broad overview of Squid architecture and details some of
Squid modules. It also discusses
how to contribute to the documentation
Auto-generated
code documentation
offers some information on the Squid internals with links to the latest
version of the code.
Finding things to do
Bugzilla
contains bugs and feature
requests.
RoadMap
lists the feature wishes and plans for future releases.
RoadMap/Tasks
itemizes general cleanup tasks that need to be done. These can be
good introductory tasks.
We have a list of
HTTP/1.1 compliance
violations
that need to be addressed.
git grep XXX
git grep TODO
Other developers are often able to provide projects for anyone just
wanting to contribute.
Discussing code
Most development discussions happen on the
developer mailing list
Please use plain-text only (no HTML email).
Testing
We run constant integration testing with a
BuildFarm
It is possible to rely on the images we use for it to test code changes
against different Linux distributions and compiler versions. We publish
these images to the
Docker Hub
. They are
named
squidcache/buildfarm--
Assuming you have access to a Docker environment, the easiest way to
test a local checkout on it is to run the command:
OS=centos-7 docker run -ti --rm -v$PWD:$PWD -w$PWD -u1000
./test-builds.sh squidcache/buildfarm-
uname -m
-$OS --verbose
--use-config-cache --cleanup
It may leave behind some files owned by UID 1000; sorry it can’t be
avoided
Detecting build errors early
It is always better to find bugs before submitting a PR for review.
Since Squid has such a large number of build permutations that can
interact to change build dependencies and outcomes the a
test-builds.sh
script is provided in the repository to check that
your code contribution will at least compile successfully. This is the
same script which will be run by the CI system in a wider range of OS
systems to prevent regressions.
In a checkout of the Squid sources branch you are proposing to submit
for PR, run:
./bootstrap.sh && ./test-builds.sh
The default stdout display just lists the ERROR and FAIL messages
produced during build. Not all of these are problems (eg stats
indicating 0 failures), a series of logs with full build output are
provided as well. See the end of the log for overall build result if you
have any doubts about the success/failure status.
The command line option
--keep-going
is provided to allow as many
error as possible to be found on one script execution. It builds with
make -k
and tries all build permutations instead of exiting on the
first compile failure.
The command line option
--verbose
is provided to allow full compile
output to stdout instead of only to logs. The logs are still produced.
Other options are available for specific build situations. See the
script for details or ask on squid-dev mailing list.
Replication of CI BuildFarm failures
On any linux system with docker installed, to reproduce a build you can
check out squid sources on a fresh directory, then run:
` OS_VERSION=fedora-32 docker run -ti –rm -u jenkins -v $PWD:$PWD -w
$PWD squidcache/buildfarm:
uname -m
-$OS_VERSION /bin/bash -l`
Replace OS_VERSION with the OS version of the CI system node which
is failing (eg, fedora-rawhide, debian-unstable)
This will drop you in the container, ready to try things out.
Getting sources
There are several ways to get Squid sources. The method you select
determines whether the sources come bootstrapped or can be easily
updated as the official code changes.
Raw sources via GitHub
The official Squid source code repository is on
GitHub
. see
GitHints
for common actions you may need to perform with the git VCS.
When working from this repository the
bootstrap.sh
script is
required to prepare ./configure and related magic. See
#Required_Build_Tools
for the required
bootstrapping and building tools.
Bootstrapped source tarballs via HTTP
The latest sources are available at address
with a series of previous daily
snapshots of the code for testing regressions and other special
circumstances.
The daily tarballs displayed are listed by date created and the
repository revision ID included in that tarball. Gaps are expected
in the list when there were no new revisions committed that day, or
when the revision failed to compile on our tarball creation machine.
:warning:
Daily tarballs contain the fully bootstrapped tool chain ready to
build. But be aware that some changes may appear with incomplete or
missing documentation.
As a more lightweight alternative you can use rsync to fetch the latest
tarball content.
Bootstrapped sources via rsync
As a more lightweight alternative to the tarballs you can use rsync; the
latest sources are available at address
rsync://squid-cache.org/source/
The rsync source mirrors the latest published sources tarball.
The
rsync sources contain the fully bootstrapped tool chain ready to build.
But be aware that some changes may appear with incomplete or missing
documentation.
To use this feature you may use
$ rsync rsync://squid-cache.org/source
(sample output)
drwxr-xr-x 512 2011/03/20 19:14:28 .
drwxr-xr-x 1024 2009/09/17 14:13:26 squid-2.6
drwxr-xr-x 1024 2011/03/20 19:14:06 squid-2.7
drwxr-xr-x 1024 2010/07/02 13:10:53 squid-2
drwxr-xr-x 1024 2010/07/02 13:17:48 squid-3.0
drwxr-xr-x 1024 2011/03/20 19:14:21 squid-3.1
drwxr-xr-x 1024 2011/03/20 19:14:26 squid-3.2
drwxr-xr-x 1024 2011/03/20 19:14:26 squid-3.3
drwxr-xr-x 1024 2011/03/20 19:14:26 squid-3.4
drwxr-xr-x 1024 2011/03/20 19:14:26 squid-3.5
drwxr-xr-x 1024 2011/03/20 19:14:13 squid-4
After you’ve selected the version you wish to download you can:
rsync -avz rsync://squid-cache.org/source/ .
Required Build Tools
autoconf 2.64 or later
automake 1.10 or later
libtool 2.6 or later
libltdl-dev
awk
ed
CppUnit
for unit
testing.
Depending on what features you wish to develop there may be other
library and tool requirements.
Building tarballs for distribution requires these additional tools:
autoconf-archive
tar
gzip
bzip2
xz
perl
When working from the repository code the
bootstrap.sh
script is
required initially to run a number of autotools to prepare ./configure
and related magic. This needs repeating after any changes to the
Makefile.am or configure.ac scripts, including changes received from the
repository updates. Common bootstrap.sh problems are discussed in
ProgrammingGuide/Bootstrap
Miscellaneous
ReleaseProcess
describes the process and criteria used by the Squid Developers when
making new Squid releases from the accepted changes.
WhoWeAre
explains who the people working on the Squid project are.
During the life of the Squid project, a number of
papers
have been published.
Navigation:
Site Search
Site Pages
Categories
🔼 go up