From 8b06f176ae31a54c53caaf3a0a23836c97dd2f28 Mon Sep 17 00:00:00 2001 From: Jim Garlick Date: Wed, 27 Sep 2023 09:09:43 -0700 Subject: [PATCH 1/3] doc: add build instructions Problem: flux-core does not ship with much info about releases or how to build them. Add a "Building Releases" section to the project docs. --- doc/Makefile.am | 1 + doc/build.rst | 130 ++++++++++++++++++++++++++++++++++++++++++++++++ doc/index.rst | 1 + 3 files changed, 132 insertions(+) create mode 100644 doc/build.rst diff --git a/doc/Makefile.am b/doc/Makefile.am index 5848dd5f0505..bdf5dddc8bea 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -394,6 +394,7 @@ EXTRA_DIST = \ domainrefs.py \ index.rst \ index_man.rst \ + build.rst \ $(RST_FILES) \ man1/index.rst \ man1/index_general.rst \ diff --git a/doc/build.rst b/doc/build.rst new file mode 100644 index 000000000000..558b42decc1e --- /dev/null +++ b/doc/build.rst @@ -0,0 +1,130 @@ +Building Releases +================= + +Version Numbering +----------------- + +Flux-core releases are numbered with +`Semantic Versioning `_, where MAJOR.MINOR.PATCH release +numbers communicate that: + +- major releases may break API + +- minor releases add functionality in a backward compatible manner + +- patch releases make backward compatible bug fixes + +At this time, the project is at major version zero, indicating interfaces +are not yet stable. That said, flux-core developers try to minimize +disruption to early adopters and announce any necessary breaking changes +in the release notes. + +Obtaining Releases +------------------ + +Tarballs and release notes are available on the +`Github releases page `_. + +Releases for all Flux framework projects are also announced on the +`Flux Framework releases page `_. + +Installing Dependencies +----------------------- + +Several external software packages are prerequisites for building Flux. +Scripts that install these packages for debian and redhat based distros are +located in the flux-core source tree ``scripts`` sub-directory. + +The following packages are optional and may be omitted if you do not require +the associated functionality: + +.. list-table:: + :header-rows: 1 + + * - Package + - Functionality + + * - `flux-security `_ + - Launching work as multiple users. + + For example when Flux is to be the native resource manager on a cluster. + + * - Sphinx + - Building man pages and documentation + + * - MPI + - Test only: sanity tests that Flux can launch MPI programs + + * - valgrind + - Test only: checks for memory errors + +Configuring and Building a Release +---------------------------------- + +flux-core uses GNU autotools internally, so it supports the usual +`Use Cases for the GNU Build System `_. A standard build follows this pattern: + +.. code-block:: console + + $ tar xzf flux-core-X.Y.Z.tar.gz + $ cd flux-core-X.Y.Z + $ ./configure --with-flux-security + $ make + $ make check + $ make install + +Configure *should* abort if any required build dependencies are missing or +insufficient. Configure options options may be listed with ``./configure +--help``. + +``make -j N`` may be used to speed up the build and check targets by +increasing parallelism. + +All checks are expected to pass, although some timing related test defects +may cause tests to sporadically fail on slow systems or when run with too much +parallelism. ``make recheck`` re-runs any failing checks. + +Packages +-------- + +RPM packages for TOSS 4 (RHEL 8 based) are produced by the TOSS build system +and can be made available externally on request. When requested, these are +manually added to the release assets on github. + +deb packages for Debian or Ubuntu can be built from a release tarball with +``make deb``, producing debs in the ``debbuild`` sub-directory. This target +is used by some Flux team members to build packages for test clusters running +the `Raspberry Pi OS `_ (Debian/GNU 11). + +Docker Images +------------- + +Docker images for tagged releases as well as a current development snapshot +are available in the `fluxrm/flux-core Dockerhub +`_. For example, the following +downloads a debian bookworm image containing flux-core 0.54.0 and starts a +flux instance within it: + +.. code-block:: console + + $ docker pull fluxrm/flux-core:bookworm-v0.54.0-amd64 + $ docker run -ti fluxrm/flux-core:bookworm-v0.54.0-amd64 + ƒ(s=1,d=0) fluxuser@080d84548cc4:~$ + +Spack +----- + +Flux-core and its dependencies can also be built using `spack +`_, for example: + +.. code-block:: console + + $ git clone --depth=100 https://github.com/spack/spack.git + $ cd spack + $ . share/spack/setup-env.sh + $ spack install flux-core@0.54.0 %gcc@11.4.0 + $ spack find flux-core + -- linux-ubuntu22.04-zen2 / gcc@11.4.0 -------------------------- + flux-core@0.54.0 + ==> 1 installed package + $ spack load flux-core diff --git a/doc/index.rst b/doc/index.rst index 5fbd4e346436..94f3c40b4efa 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -97,5 +97,6 @@ Table of Contents .. toctree:: :maxdepth: 2 + build index_man python/index From f4590555259ca97025e5493074ec924072ae2022 Mon Sep 17 00:00:00 2001 From: Jim Garlick Date: Thu, 28 Sep 2023 08:51:59 -0700 Subject: [PATCH 2/3] doc: add license and support information Problem: flux-core does not include an overview of project support and licensing. Add a support page to the project docs. --- doc/Makefile.am | 2 ++ doc/images/lgplv3-147x51.png | Bin 0 -> 3343 bytes doc/index.rst | 1 + doc/support.rst | 57 +++++++++++++++++++++++++++++++++++ 4 files changed, 60 insertions(+) create mode 100644 doc/images/lgplv3-147x51.png create mode 100644 doc/support.rst diff --git a/doc/Makefile.am b/doc/Makefile.am index bdf5dddc8bea..1dc2f1641b19 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -395,6 +395,8 @@ EXTRA_DIST = \ index.rst \ index_man.rst \ build.rst \ + support.rst \ + images/lgplv3-147x51.png \ $(RST_FILES) \ man1/index.rst \ man1/index_general.rst \ diff --git a/doc/images/lgplv3-147x51.png b/doc/images/lgplv3-147x51.png new file mode 100644 index 0000000000000000000000000000000000000000..012f011becd9969943d83a032a46afcd4379c5a6 GIT binary patch literal 3343 zcmV+q4e;`bP)4bM zJ)E`ny6)dz>%Fb@<%-2(xe`b~BG<6mB?zquj}qn)wh=N3F~WJmCc^WC^8YK7n79NO zf$|XA5|%OID11v;Pnb@aK$t?)cz|3KJGBzcff zQA56(gbg5Gogie|mLNzVEV%SSa&G@l6OIwiv$W%cu|$kQ0amlJgp-5}Qz8{3Tucxo z5IPXnHddxrIGblkmM}JgqP{W3!kvbJ<1?l*cy4GG zkw|G}0|~7OpL&q2K^*K-m0=c`X=G=@SIRq9k>xeDFcB?8d*cX843I9$J;CZ6EAl#r ztaB3Tn=aD(YsPcL@Hrc}KzIr(^kR=^b`Z*H-fscIb%e^g=Uj+XfbbDkrRt_+n#MYI zNaQ_k!8lfw)t3jFkV)D4qA$x?UOSPu%&^XSqMTzV>Lt>3f^`Oa?zT7*Nv-G&2wh<_ zGA0sCJzYS+GeSJ5Wk{ykkd=BFyHlw0Pgr9MH7_s>Q@`eDG5lY|&>!7_=Iy>9}cFk!srxhsgI{w7QohDwQA21M!yB2D?fbRQxW zWkRUJLqahBI^x90?c=wG;%>%3N!bLwm<(*68xw~6O(i7-c*Sap*KBMs%gUj`VngY`Kv3zJ%l=1lI69rFp#@M zd+%7NbDXGih+(;hMY)McpCQtJV^G%(E^|3Cz!*-#K9$Vmws=5oZKVTRyi*7VlmH%- zOx#KNX+R;=#8$$|ndIV23WIhb?O=^WImgTXfJmPmRH;C@u7>^i3a*;mkOkvKBxQ6> z3F$(asls@Jl4*;^9`v`U)>~0uO^@f^Ld2pMUKP(vW2K2otQ@xaS(*IIiCaU|x6`1$ zS}t>$YEbU5(;keH@gR}$GxT^D~-wIBDnSx0_E9=gL+A{_kiC^_ULC-jj=Kh z419iQAj)-M+GbJ+IkC1!Uw3HAe4%_}cy3snh;*3Cy&;K|9|s8L2O-n#UUGo)iCGv} zUjsA4UY8f2s*&p!Scnp6h=Tx8w9R@Rb&uBw+qEoev~HNs#fk`IY6}6peGoEn2kvo^ z_mG9b-6ZPVZdk6HMy~sv$m@jd!UW3UdB~Es+1z7J@9=oOEAorOU1F0&$6buE1z`M~ z0Wo4D{;g|3rq>B)2nB_j}A~K5U&{ zPGQ>u_ZBBy2oC2CkTJdNWU~xcrDp=!nS_`9F_9Pb>sce}OE(Pw)5vw-aR;UF_=go# zON7)m2Wqy_IYKqh8>j7UG5mPHQZ_UZX5uy8mKq`zBOD~`(H(?jSH?!_}-I>y2{Y;Wta0tHc${^YYNO~a~`u6@pBz}>_- ztNcO^i8|P}n!^e@$QAOB8jt^=h<%(X>g!|0VR~87P%CEB5Qf!wVS+9$oCwqjM4II* zQ@IRyvL%PslCO6NNI=-8*16d8RbA`Z=V(EPFzy) zF`;M}GJV7v9Iwd>-kT1aenNe~~xc za1x#q<+^woE1AbXEZ+5rHZ?)Ii~DIe5063mmsv=p*Cfe3h*X2HAFEQ`K<`=%Zm`#u z6oE{AS)FYx)w#$mF5Qw}YgEWS@x!PCSo&SuI4NSIvVugP%j0AkA~hqNAbdk;5_k?Y zLhX8}vQe>$AC81dUm(QGDgc##o}tG-EZT%5(;T<$9IMh+sWD+Z@xC%=u-}%(h}0Rv zwvv%<3^fNDp*G%{#OKgtOt4dP9DA2|HtNx$JpuZ~!J|?SGV8ul9=dxFFdmv*CJttl zHzZLqVGPv&O>PGT0+UGywFyK=WoD!-??I+97TY_7`ceZpZc7o~0g+zu^0|c}Q6pc|bbT?fE3U{OS&fA|b*^@)CyQAf;0Mn_IicBBYmHsr$Dw zA=`#!ygRPJ=>%EhWzDmlV8&RCBT{>EAel}|&CZ8ZB`~g8P=uD_qf%oWPPk7+O}H6E z0}$zE!WL|6OVoXoR&PZKaW&3K7%+Ene-v&+xfL%~eU(iJkFe0$C9v5HaIsJyLqFCs zf6+qr|3)|vdIE7pDL9YTh56zdB7Y1FbEgsHw;wl!)J35FX5=+Qy;GrWb;D`h4=j_) z`c*a|SECWQ{zj?&UE|UYUPhCk=iLx8TMgI7s29-~aoMYJ#ml=$8w)o~MZ^TPcX7mC zaQtg8cf%I57TATC;n=8}ArLG-@D$>8^0Kr) zxL9Woqpp$6I$ViG6|}@r@9E4c-2wMG#Sp*K7U%ucDpUqm=M3DgQXGU^jMFvuq1+2d zcluV-GMTz%6NyrBfbt>?kv-zxCSKedK_U>vQKzHA``;Xf#jQAzdH@d1iP!?~adDj1 z0-+D$;!ayibc#o+!}N9a!|k`qY8$hFrR%`?9JY!}heDFcqtf zg9Y&3f6eYiI*QwE?^i!6m}7shF7cy%S#JL+g}aU>!nJXck;Wm8T6ty>9)m+R_th}A Z{{kwc4yr0Vl(YZ<002ovPDHLkV1jf3FPs1X literal 0 HcmV?d00001 diff --git a/doc/index.rst b/doc/index.rst index 94f3c40b4efa..484c896ef4c8 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -98,5 +98,6 @@ Table of Contents :maxdepth: 2 build + support index_man python/index diff --git a/doc/support.rst b/doc/support.rst new file mode 100644 index 000000000000..8b99605d1097 --- /dev/null +++ b/doc/support.rst @@ -0,0 +1,57 @@ +License and Support +=================== + +License +------- + +.. figure:: images/lgplv3-147x51.png + :alt: LGPL-3.0 logo + :align: right + +Flux-core is licensed under `LGPL-3.0 +`_ which means project forks +must retain the same license and follow the license's requirements for making +source code available to end users. + +Software that merely uses flux-core's APIs may be independently licensed. + +Support +------- + +All flux-core issues and changes are proposed and discussed on `Github +`_. The team values +openness and inclusivity and encourages collaboration. Engage with us! + +If you have a problem that might be a flux-core bug, please first search +existing issues, then open a new `Github issue +`_ if necessary. +Be sure to include relevant context and especially the flux version that +is exhibiting the problem: + +.. code-block:: console + + $ flux version + commands: 0.54.0 + libflux-core: 0.54.0 + libflux-security: 0.10.0 + build-options: +systemd+hwloc==2.4.0+zmq==4.3.4 + +`Github discussions `_ +are sometimes useful too. + +Development Commitment +---------------------- + +At this time, Lawrence Livermore National Laboratory (LLNL) has a team of +four full time employees working on flux-core, and several additional employees +and collaborators working on the broader Flux Framework and related research +areas. LLNL is committed to making Flux a production quality tool for HPC +workload management, and has sustained its investment for over a decade thus +far. + +Flux is part of the `TOSS `_ +operating system and thus is supported across multiple U.S. national laboratory +facilities. + +The Flux team welcomes all users and contributors to the Flux community and +will do its best enable the community to grow and thrive. From bac7f35d8d72418ec192ae8ca8655b08e0f2a886 Mon Sep 17 00:00:00 2001 From: Jim Garlick Date: Thu, 28 Sep 2023 09:22:07 -0700 Subject: [PATCH 3/3] testsuite: spell check doc/*.rst Problem: doc/*.rst files are not spell checked by 'make check'. Add *.rst to the list of spellcheck targets. --- doc/test/spell.en.pws | 20 ++++++++++++++++++++ doc/test/spellcheck | 2 +- 2 files changed, 21 insertions(+), 1 deletion(-) diff --git a/doc/test/spell.en.pws b/doc/test/spell.en.pws index 2e66068caa87..b8875ff8a8e6 100644 --- a/doc/test/spell.en.pws +++ b/doc/test/spell.en.pws @@ -718,3 +718,23 @@ MemoryMax MemoryLow MemoryMin myattr +autotools +cd +debbuild +debian +distros +dockerhub +fluxrm +LLNL +redhat +RHEL +spack +ubuntu +xzf +APIs +HPC +infinitum +OpenMPI +inclusivity +lgplv +png diff --git a/doc/test/spellcheck b/doc/test/spellcheck index 9c89adbc78c7..c991663583ca 100755 --- a/doc/test/spellcheck +++ b/doc/test/spellcheck @@ -1,7 +1,7 @@ #!/bin/bash if test $man_base_dir; then - set ${man_base_dir}/man*/*.rst ${man_base_dir}/man*/common/*.rst + set ${man_base_dir}/*.rst ${man_base_dir}/man*/*.rst ${man_base_dir}/man*/common/*.rst fi if test $# == 0; then