From 04fb351b69a2f1789e16b543c7fc8f6f117ffb9b Mon Sep 17 00:00:00 2001 From: Guilherme Amadio Date: Fri, 23 Jun 2023 17:20:46 +0200 Subject: [PATCH] Update README files and convert to Markdown Co-authored-by: Andrew Hanushevsky --- MANIFEST.in | 2 +- README | 83 --------- README.md | 99 ++++++++++ bindings/python/README | 6 - bindings/python/README.md | 236 ++++++++++++++++++++++++ bindings/python/docs/source/install.rst | 2 +- bindings/python/setup.py | 2 +- setup.py | 2 +- 8 files changed, 339 insertions(+), 93 deletions(-) delete mode 100644 README create mode 100644 README.md delete mode 100644 bindings/python/README create mode 100644 bindings/python/README.md diff --git a/MANIFEST.in b/MANIFEST.in index c39b67a5b56..e348ad7b7e9 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,7 +1,7 @@ include *.sh *.py *.in include CMakeLists.txt include COPYING* LICENSE -include VERSION README +include VERSION README.md recursive-include bindings * recursive-include cmake * diff --git a/README b/README deleted file mode 100644 index 4df5d8ff7b2..00000000000 --- a/README +++ /dev/null @@ -1,83 +0,0 @@ - --------------------------------------------------------------------------------- - _ _ ______ _____ - \ \ / (_____ \ _ (____ \ - \ \/ / _____) ) ___ ___ | |_ _ \ \ - ) ( (_____ ( / _ \ / _ \| _)| | | | - / /\ \ | | |_| | |_| | |__| |__/ / - /_/ \_\ |_|\___/ \___/ \___)_____/ - --------------------------------------------------------------------------------- - -1. S U P P O R T E D O P E R A T I N G S Y S T E M S - - XRootD is supported on the following platforms: - - * RedHat Enterprise Linux 7 or greater and their derivatives (Scientific Linux) - compiled with gcc - * MacOSX 10.6 or greater compiled with gcc or clang - -2. B U I L D I N S T R U C T I O N S - -2.0 Build dependecies - - XRootD requires at minimum following packages (RHEL distro): - - * gcc-c++ cmake(3) krb5-devel libuuid-devel libxml2-devel openssl-devel systemd-devel zlib-devel - * devtoolset-7 (only RHEL7) - -2.1 Build system - - XRootD uses CMake to handle the build process. It should build fine with -cmake 3.6 or greater. It may be also possible to use version 2.8 but this -is neither recommended nor supported. - -2.2 Build parameters - - The build process supports the following parameters: - - * CMAKE_INSTALL_PREFIX - indicates where the XRootD files should be installed, - (default: /usr) - * CMAKE_BUILD_TYPE - type of the build: Release/Debug/RelWithDebInfo - * FORCE_32BITS - Force building 32 bit binaries when on Solaris AMD64 - (default: FALSE) - * ENABLE_PERL - enable the perl bindings if possible (default: TRUE) - * ENABLE_FUSE - enable the fuse filesystem driver if possible - (default: TRUE) - * ENABLE_KRB5 - enable the Kerberos 5 authentication if possible - (default: TRUE) - * ENABLE_READLINE - enable the lib readline support in the commandline - utilities (default: TRUE) - * OPENSSL_ROOT_DIR - path to the root of the openssl installation if it - cannot be detected in a standard location - * KERBEROS5_ROOT_DIR - path to the root of the kerberos installation if it - cannot be detected in a standard location - * READLINE_ROOT_DIR - path to the root of the readline installation if it - cannot be detected in a standard location - * CMAKE_C_COMPILER - path to the c compiler that should be used - * CMAKE_CXX_COMPILER - path to the c++ compiler that should be used - -2.3 Build steps - - * on RHEL7 only: scl enable devtoolset-7 /bin/bash - - * Create an empty build directory: - - mkdir build - cd build - - * Generate the build system files using cmake, ie: - - cmake /path/to/the/xrootd/source -DCMAKE_INSTALL_PREFIX=/opt/xrootd \ - -DENABLE_PERL=FALSE - - * Build the source: - - make - - * Install the source: - - make install - -3. P L A T F O R M N O T E S - * None. diff --git a/README.md b/README.md new file mode 100644 index 00000000000..a79193927f0 --- /dev/null +++ b/README.md @@ -0,0 +1,99 @@ +

+ +

+ +## XRootD: eXtended ROOT Daemon + +The [XRootD](http://xrootd.org) project provides a high-performance, +fault-tolerant, and secure solution for handling massive amounts of data +distributed across multiple storage resources, such as disk servers, tape +libraries, and remote sites. It enables efficient data access and movement in a +transparent and uniform manner, regardless of the underlying storage technology +or location. It was initially developed by the High Energy Physics (HEP) +community to meet the data storage and access requirements of the BaBar +experiment at SLAC and later extended to meet the needs of experiments at the +Large Hadron Collider (LHC) at CERN. XRootD is the core technology powering the +[EOS](https://eos-web.web.cern.ch/) distributed filesystem, which is the storage +solution used by LHC experiments and the storage backend for +[CERNBox](https://cernbox.web.cern.ch/). XRootD is also used as the core +technology for global CDN deployments across multiple science domains. + +XRootD is based on a scalable architecture that supports multi-protocol +communications. XRootD provides a set of plugins and tools that allows the user +to configure it freely to deploy data access clusters of any size, and which can +include sophisticated features such as erasure coded files, various methods of +authentication and authorization, as well as integration with other storage +systems like [ceph](https://ceph.io). + +## Documentation + +Genral documentation such as configuration reference guides, and user manuals +can be found on the XRootD website at http://xrootd.org/docs.html. + +## Supported Operating Systems + +XRootD is officially supported on the following platforms: + + * RedHat Enterprise Linux 7 or later and their derivatives + * Debian 11 and Ubuntu 22.04 or later + * macOS 11 (Big Sur) or later + +Support for other operating systems is provided by the community. + +## Installation Instructions + +XRootD is available via official channels in most operating systems. +Installation via the system package manager should be preferred if possible. + +In RPM-based distributions, like CentOS, Alma, Rocky, Fedora, etc, one can +search and install XRootD packages with + +```sh +$ yum search xrootd +$ sudo yum install xrootd* python3-xrootd +``` +or +```sh +$ dnf search xrootd +$ sudo dnf install xrootd* python3-xrootd +``` + +In some distributions, it may be necessary to first install the EPEL release +repository with `yum install epel-release` or `dnf install epel-release`. + +On Debian 11 or later, and Ubuntu 22.04 or later, XRootD can be installed via apt + +```sh +$ apt search xrootd +$ sudo apt install xrootd* python3-xrootd +``` + +On macOS, XRootD is available via Homebrew +```sh +$ brew install xrootd +``` + +Finally, it is also possible to install the XRootD python bindings from PyPI +using pip: +``` +$ pip install xrootd +``` + +For detailed instructions on how to build and install XRootD from source code, +please see [docs/INSTALL.md](docs/INSTALL.md) in this repository. + +## User Support and Bug Reports + +Bugs should be reported using [GitHub issues](https://github.com/xrootd/xrootd/issues). +You can open a new ticket by clicking [here](https://github.com/xrootd/xrootd/issues/new). + +For general questions about XRootD, you can send a message to our user mailing +list at xrootd-l@slac.stanford.edu. Please check XRootD's contact page at +http://xrootd.org/contact.html for further information. + +## Contributing + +User contributions can be submitted via pull request on GitHub. We recommend +that you create your own fork of XRootD on GitHub and use it to submit your +patches. For more detailed instructions on how to contribute, please refer to +the file [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md). diff --git a/bindings/python/README b/bindings/python/README deleted file mode 100644 index 059782ec5f0..00000000000 --- a/bindings/python/README +++ /dev/null @@ -1,6 +0,0 @@ -# XRootD Python Bindings - -This is a set of simple but pythonic bindings for XRootD. It is designed to make -it easy to interface with the XRootD client, by writing Python instead of having -to write C++. - diff --git a/bindings/python/README.md b/bindings/python/README.md new file mode 100644 index 00000000000..17c08f144b1 --- /dev/null +++ b/bindings/python/README.md @@ -0,0 +1,236 @@ +## XRootD Python Bindings + +This is a set of simple but pythonic bindings for XRootD. It is designed to make +it easy to interface with the XRootD client, by writing Python instead of having +to write C++. + +## Installation + +For general instructions on how to use `pip` to install Python packages, please +take a look at https://packaging.python.org/en/latest/tutorials/installing-packages/. +The installation of XRootD and its Python bindings follows for the most part the +same procedure. However, there are some important things that are specific to +XRootD, which we discuss here. Since XRootD 5.6, it is possible to use `pip` to +install only the Python bindings, building it against a pre-installed version of +XRootD. In this case, we recommend using the same version of XRootD for both +parts, even if the newer Python bindings should be usable with older versions of +XRootD 5.x. Suppose that XRootD is installed already into `/usr`. Then, one can +build and install the Python bindings as shown below. + +```sh +xrootd $ cd bindings/python +python $ python3 -m pip install --target install/ . +Processing xrootd/bindings/python + Installing build dependencies ... done + Getting requirements to build wheel ... done + Installing backend dependencies ... done + Preparing metadata (pyproject.toml) ... done +Building wheels for collected packages: xrootd + Building wheel for xrootd (pyproject.toml) ... done + Created wheel for xrootd: filename=xrootd-5.6-cp311-cp311-linux_x86_64.whl size=203460 sha256=8bbd9168... + Stored in directory: /tmp/pip-ephem-wheel-cache-rc_kb_nx/wheels/af/1b/42/bb953908... +Successfully built xrootd +Installing collected packages: xrootd +``` + +The command above installs the Python bindings into the `install/` directory in +the current working directory. The structure is as shown below + +```sh +install/ +|-- XRootD +| |-- __init__.py +| |-- __pycache__ +| | |-- __init__.cpython-311.pyc +| |-- client +| |-- __init__.py +| |-- __pycache__ +| | |-- __init__.cpython-311.pyc +| | |-- _version.cpython-311.pyc +| | |-- copyprocess.cpython-311.pyc +| | |-- env.cpython-311.pyc +| | |-- file.cpython-311.pyc +| | |-- filesystem.cpython-311.pyc +| | |-- finalize.cpython-311.pyc +| | |-- flags.cpython-311.pyc +| | |-- glob_funcs.cpython-311.pyc +| | |-- responses.cpython-311.pyc +| | |-- url.cpython-311.pyc +| | |-- utils.cpython-311.pyc +| |-- _version.py +| |-- copyprocess.py +| |-- env.py +| |-- file.py +| |-- filesystem.py +| |-- finalize.py +| |-- flags.py +| |-- glob_funcs.py +| |-- responses.py +| |-- url.py +| |-- utils.py +|-- pyxrootd +| |-- __init__.py +| |-- __pycache__ +| | |-- __init__.cpython-311.pyc +| |-- client.cpython-311-x86_64-linux-gnu.so +|-- xrootd-5.6.dist-info + |-- INSTALLER + |-- METADATA + |-- RECORD + |-- REQUESTED + |-- WHEEL + |-- direct_url.json + |-- top_level.txt + +8 directories, 36 files +``` + +If you would like to install it for your own user, then use `pip install --user` +instead of `--target`. + +If XRootD is not already installed into the system, then you will want to +install both the client libraries and the Python bindings together using `pip`. +This is possible by using the `setup.py` at the top level of the project, rather +than the one in the `bindings/python` subdirectory. + +```sh +xrootd $ python3 -m pip install --target install/ . +Processing xrootd + Installing build dependencies ... done + Getting requirements to build wheel ... done + Installing backend dependencies ... done + Preparing metadata (pyproject.toml) ... done +Building wheels for collected packages: xrootd + Building wheel for xrootd (pyproject.toml) ... done + Created wheel for xrootd: filename=xrootd-5.6-cp311-cp311-linux_x86_64.whl size=65315683 sha256=a2e7ff52... + Stored in directory: /tmp/pip-ephem-wheel-cache-9g6ovy4q/wheels/47/93/fc/a23666d3... +Successfully built xrootd +Installing collected packages: xrootd +Successfully installed xrootd-5.6 +``` + +In this case, the structure is a bit different than before: + +```sh +xrootd $ tree install/ +install/ +|-- XRootD +| |-- __init__.py +| |-- __pycache__ +| | |-- __init__.cpython-311.pyc +| |-- client +| |-- __init__.py +| |-- __pycache__ +| | |-- __init__.cpython-311.pyc +| | |-- _version.cpython-311.pyc +| | |-- copyprocess.cpython-311.pyc +| | |-- env.cpython-311.pyc +| | |-- file.cpython-311.pyc +| | |-- filesystem.cpython-311.pyc +| | |-- finalize.cpython-311.pyc +| | |-- flags.cpython-311.pyc +| | |-- glob_funcs.cpython-311.pyc +| | |-- responses.cpython-311.pyc +| | |-- url.cpython-311.pyc +| | |-- utils.cpython-311.pyc +| |-- _version.py +| |-- copyprocess.py +| |-- env.py +| |-- file.py +| |-- filesystem.py +| |-- finalize.py +| |-- flags.py +| |-- glob_funcs.py +| |-- responses.py +| |-- url.py +| |-- utils.py +|-- pyxrootd +| |-- __init__.py +| |-- __pycache__ +| | |-- __init__.cpython-311.pyc +| |-- client.cpython-311-x86_64-linux-gnu.so +| |-- libXrdAppUtils.so +| |-- libXrdAppUtils.so.2 +| |-- libXrdAppUtils.so.2.0.0 +| |-- libXrdCl.so +| |-- libXrdCl.so.3 +| |-- libXrdCl.so.3.0.0 +| |-- libXrdClHttp-5.so +| |-- libXrdClProxyPlugin-5.so +| |-- libXrdClRecorder-5.so +| |-- libXrdCrypto.so +| |-- libXrdCrypto.so.2 +| |-- libXrdCrypto.so.2.0.0 +| |-- libXrdCryptoLite.so +| |-- libXrdCryptoLite.so.2 +| |-- libXrdCryptoLite.so.2.0.0 +| |-- libXrdCryptossl-5.so +| |-- libXrdPosix.so +| |-- libXrdPosix.so.3 +| |-- libXrdPosix.so.3.0.0 +| |-- libXrdPosixPreload.so +| |-- libXrdPosixPreload.so.2 +| |-- libXrdPosixPreload.so.2.0.0 +| |-- libXrdSec-5.so +| |-- libXrdSecProt-5.so +| |-- libXrdSecgsi-5.so +| |-- libXrdSecgsiAUTHZVO-5.so +| |-- libXrdSecgsiGMAPDN-5.so +| |-- libXrdSeckrb5-5.so +| |-- libXrdSecpwd-5.so +| |-- libXrdSecsss-5.so +| |-- libXrdSecunix-5.so +| |-- libXrdSecztn-5.so +| |-- libXrdUtils.so +| |-- libXrdUtils.so.3 +| |-- libXrdUtils.so.3.0.0 +| |-- libXrdXml.so +| |-- libXrdXml.so.3 +| |-- libXrdXml.so.3.0.0 +|-- xrootd-5.6.dist-info + |-- COPYING + |-- COPYING.BSD + |-- COPYING.LGPL + |-- INSTALLER + |-- LICENSE + |-- METADATA + |-- RECORD + |-- REQUESTED + |-- WHEEL + |-- direct_url.json + |-- top_level.txt + +8 directories, 78 files +``` + +As can be seen above, now all client libraries have been installed alongside the +C++ Python bindings library (`client.cpython-311-x86_64-linux-gnu.so`). When +installing via `pip` by simply calling `pip install xrootd`, the package that +gets installed is in this mode which includes the libraries. However, command +line tools are not included. + +Binary wheels are supported as well. They can be built using the `wheel` +subcommand instead of `install`: + +```sh +xrootd $ python3.12 -m pip wheel . +Processing xrootd + Installing build dependencies ... done + Getting requirements to build wheel ... done + Installing backend dependencies ... done + Preparing metadata (pyproject.toml) ... done +Building wheels for collected packages: xrootd + Building wheel for xrootd (pyproject.toml) ... done + Created wheel for xrootd: filename=xrootd-5.6-cp312-cp312-linux_x86_64.whl size=65318541 sha256=6c4ed389... + Stored in directory: /tmp/pip-ephem-wheel-cache-etujwyx1/wheels/cf/67/3c/514b21dd... +Successfully built xrootd +``` + +If you want to have everything installed, that is, server, client, command line +tools, etc, then it is recommended to use CMake to build the project, and use +the options `-DENABLE_PYTHON=ON -DINSTALL_PYTHON_BINDINGS=ON` so that CMake +takes care of calling `pip` to install the Python bindings compiled together +with the other components in the end. The option `-DPIP_OPTIONS` can be used to +pass on options to pip, but it should never be used to change the installation +prefix, as that is handled by CMake. Please see [INSTALL.md](../../docs/INSTALL.md) +for full instructions on how to build XRootD from source using CMake. diff --git a/bindings/python/docs/source/install.rst b/bindings/python/docs/source/install.rst index b382321edde..abcdd555839 100644 --- a/bindings/python/docs/source/install.rst +++ b/bindings/python/docs/source/install.rst @@ -2,5 +2,5 @@ **Installing** ``pyxrootd`` =========================== -.. include:: ../../README.rst +.. include:: ../../README.md :start-line: 8 diff --git a/bindings/python/setup.py b/bindings/python/setup.py index 226607c2756..33e4689a6dd 100644 --- a/bindings/python/setup.py +++ b/bindings/python/setup.py @@ -123,7 +123,7 @@ def build_extensions(self): download_url='https://github.com/xrootd/xrootd/archive/v%s.tar.gz' % version, keywords=['XRootD', 'network filesystem'], license='LGPLv3+', - long_description=open(srcdir + '/README').read(), + long_description=open(srcdir + '/README.md').read(), long_description_content_type='text/plain', packages = ['XRootD', 'XRootD.client', 'pyxrootd'], package_dir = { diff --git a/setup.py b/setup.py index dac6967face..16deb9457a3 100644 --- a/setup.py +++ b/setup.py @@ -96,7 +96,7 @@ def build_extensions(self): download_url='https://github.com/xrootd/xrootd/archive/v%s.tar.gz' % version, keywords=['XRootD', 'network filesystem'], license='LGPLv3+', - long_description=open('README').read(), + long_description=open('README.md').read(), long_description_content_type='text/plain', packages = ['XRootD', 'XRootD.client', 'pyxrootd'], package_dir = {