Documentation request

[sdarwin]

Hi,

The repo has the script xapian_wheel_builder.sh but it's not mentioned in the documention (which is the README file, correct?).

How about adding this to the README?

• Full example of using xapian_wheel_builder.sh to install xapian. (even if that is only two lines of code. An explanation of what it is, show how to run it)
• How does the final result differ between install_xapian.sh and xapian_wheel_builder.sh? Why would you prefer one or the other? In which cases would you use one or the other? Which is recommended? What would happen if you run xapian_wheel_builder.sh in a venv or not in a venv? (I built the wheel without manually activating a venv. The wheel build succeeded, so maybe not important).
• It's somewhat unexpected that the installation of the search engine itself (xapian) depends on scripts that are maintained in an external xapian-haystack repo. Why wouldn't these installation scripts be originating from the top-level xapian project?

Or add a docs/advanced_topics.md file, and elaborate there without any restrictions. :-)

[asedeno]

Hi!

I wrote xapian_wheel_builder.sh because install_xapian.sh is slow and someone introduced it into the deployment process at a former job, which added significant time to our deployments. Giving that process a wheel that ~instantly installed xapian and its bindings was much nicer.

The intent of xapian_wheel_builder.sh is to prepare a wheel that, when added to a virtualenv, provides xapian and its python bindings, much like install_xapian.sh does, It has a couple of advantages:

• You can build the wheel once and use it in many virtualenvs for that platform
• the wheel does not bring any along any of xapian's compile-time dependences

It's used, for instance, in the github actions in this repository, to reduce ci runtime by building xapian once (per platform+python+xapian version, per cache lifetime) and reusing the wheel across matching runs. (see: .github/workflows/test.yml)

For a random one-off virtualenv, I'd probably just use install_xapian.sh. For a production deployment process, or installations across multiple virtualenvs on the same platform, or for a cleaner installation, I'd build a wheel and install it.

The script itself describes how to run it, but the gist of it is give it a xapian version, optionally a path to a specific version of python3, get a wheel. Building the wheel is done in a temporary virtualenv, not in any viritualenv you may or may not have active.

As for where the script lives, it was meant to be an alternative to xapian-haystack's install_xapian.sh, and that was here, so here's where I contributed it.

[sdarwin]

Thanks for the reply. BTW, I have discovered yet another xapian installation method. apt-get install -y python3-xapian, and then if using a venv ln -s /usr/lib/python3/dist-packages/xapian ${venv_path}/lib/site-packages/xapian