From 73be481acc2530d70d7f47045d143c56ac088459 Mon Sep 17 00:00:00 2001 From: Daniel Markstedt Date: Sat, 1 Jun 2024 07:25:03 +0900 Subject: [PATCH] docs: Restructure sources and touch up compile.xml script --- .github/workflows/build.yml | 6 +- configure.ac | 2 +- doc/{manual => }/generate_compile_docs.py | 75 ++-- doc/html.xsl.in | 2 +- doc/manual/.gitignore | 2 +- doc/manual/Makefile.am | 4 +- doc/manual/compile.xml | 402 ++++++++++++++---- doc/manual/meson.build | 6 +- .../{netatalk.html.in => pageheader.txt.in} | 0 doc/{manual => }/requirements.txt | 0 10 files changed, 373 insertions(+), 126 deletions(-) rename doc/{manual => }/generate_compile_docs.py (52%) rename doc/manual/{netatalk.html.in => pageheader.txt.in} (100%) rename doc/{manual => }/requirements.txt (100%) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index f36552f7fb..fc3d9579dc 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -169,7 +169,7 @@ jobs: run: ninja -C build uninstall build-fedora: - name: Fedora + name: Fedora Linux runs-on: ubuntu-22.04 container: image: fedora:latest @@ -265,9 +265,7 @@ jobs: meson setup build \ -Dbuild-tests=true \ -Denable-macos=true \ - -Dwith-bdb=/opt/homebrew/opt/berkeley-db \ - -Dwith-ssl-dir=/opt/homebrew/opt/libressl \ - -Denable-macos=true + -Dwith-bdb=/opt/homebrew/opt/berkeley-db - name: Meson - Build run: ninja -C build - name: Meson - Tests diff --git a/configure.ac b/configure.ac index 515f03ac90..092136da11 100644 --- a/configure.ac +++ b/configure.ac @@ -1162,7 +1162,7 @@ AC_CONFIG_FILES([Makefile doc/man.xsl doc/manual/Makefile doc/manual/manual.xml - doc/manual/netatalk.html + doc/manual/pageheader.txt doc/manpages/Makefile doc/manpages/man1/Makefile doc/manpages/man3/Makefile diff --git a/doc/manual/generate_compile_docs.py b/doc/generate_compile_docs.py similarity index 52% rename from doc/manual/generate_compile_docs.py rename to doc/generate_compile_docs.py index 010e58d18e..0ccf2b78a4 100755 --- a/doc/manual/generate_compile_docs.py +++ b/doc/generate_compile_docs.py @@ -2,54 +2,60 @@ # This script generates the compile.xml manual page from the GitHub build.yml file. +import datetime import re -import yaml import xmltodict +import yaml + +now = datetime.datetime.now() +date_time = now.strftime("%Y-%m-%d") + +lang_en = { + "title_1": "Compile Netatalk from Source", + "title_2": "Overview", + "title_3": "Operating Systems", + "heading_1": "Install required packages", + "heading_2": "Configure and build", + "para_1": "This appendix describes how to compile Netatalk from source for specific operating systems.", + "para_2": "Please note that the steps below are automatically generated, and may not be optimized for your system.", + "para_3": "Choose one of the build systems: Autotools or Meson. Test steps are optional.", +} + +output_en = "./manual/compile.xml" -def main(): - with open('../../.github/workflows/build.yml', 'r') as file: - workflow = yaml.safe_load(file) +with open('../.github/workflows/build.yml', 'r') as file: + workflow = yaml.safe_load(file) - apt_packages_pattern = r'\$\{\{\senv\.APT_PACKAGES\s\}\}' - apt_packages = workflow["env"]["APT_PACKAGES"] +apt_packages_pattern = r'\$\{\{\senv\.APT_PACKAGES\s\}\}' +apt_packages = workflow["env"]["APT_PACKAGES"] +def generate_docbook(strings, output_file): docbook = { "appendix": { "@id": "compile", - "title": "Compile Netatalk from Source", + "appendixinfo": [ + { + "pubdate": date_time + }, + ], + "title": strings["title_1"], "sect1": [ { "@id": "compile-overview", - "title": "Overview", + "title": strings["title_2"], }, { "para": [ - """ - This section describes how to compile Netatalk from source for specific operating systems. - """, - """ - The Netatalk project is in the process of transitioning the build system - from GNU Autotools to Meson. - During the transitional period, - the documentation will contain both Autotools and Meson build instructions. - """, - """ - Please note that this document is automatically generated from the GitHub workflow YAML file. - This may or may not be the most optimal way to build Netatalk for your system. - """, + strings["para_1"], + strings["para_2"], + strings["para_3"], ], }, { "@id": "compile-os", - "title": "Operating Systems", + "title": strings["title_3"], }, { - "para": [ - """ - Note: You only have to use execute the steps for one of the build systems, not both. - Additionally, the test steps are entirely optional for compiling from source. - """, - ], "sect2": [], } ], @@ -58,7 +64,7 @@ def main(): for key, value in workflow["jobs"].items(): sections = {} - # Skip the SonarQube job + # Skip the SonarCloud job if value["name"] != "Static Analysis": sections["@id"] = key sections["title"] = value["name"] @@ -76,9 +82,9 @@ def main(): # The vmactions jobs have a different structure if "uses" in step and step["uses"].startswith("vmactions/"): - para.append("Install dependencies") + para.append(strings["heading_1"]) para.append({"screen": step["with"]["prepare"]}) - para.append("Configure and build") + para.append(strings["heading_2"]) para.append({"screen": step["with"]["run"]}) else: para.append(step["name"]) @@ -90,10 +96,9 @@ def main(): xml = xmltodict.unparse(docbook, pretty=True) - with open('compile.xml', 'w') as file: + with open(output_file, 'w') as file: file.write(xml) - print("Wrote compile.xml") + print("Wrote to " + output_file) -if __name__ == '__main__': - main() +generate_docbook(lang_en, output_en) diff --git a/doc/html.xsl.in b/doc/html.xsl.in index 162d39edf1..60f0eaf412 100644 --- a/doc/html.xsl.in +++ b/doc/html.xsl.in @@ -9,7 +9,7 @@ - + diff --git a/doc/manual/.gitignore b/doc/manual/.gitignore index 7dc01581d7..468fee26d9 100644 --- a/doc/manual/.gitignore +++ b/doc/manual/.gitignore @@ -1,3 +1,3 @@ manual.xml -netatalk.html +pageheader.txt *.html diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am index 4cd60e945c..c83cedfa87 100644 --- a/doc/manual/Makefile.am +++ b/doc/manual/Makefile.am @@ -19,7 +19,7 @@ EXTRA_DIST = \ install.xml \ intro.xml \ manual.xml.in \ - netatalk.html.in \ + pageheader.txt.in \ upgrade.xml HTML_PAGES = \ @@ -70,7 +70,7 @@ HTML_PAGES = \ uniconv.1.html \ upgrade.html -DISTCLEANFILES = manual.xml natatalk.html +DISTCLEANFILES = manual.xml pageheader.txt if HAVE_XSLTPROC CLEANFILES += $(HTML_PAGES) diff --git a/doc/manual/compile.xml b/doc/manual/compile.xml index 8beea90f0b..2f0513b7bc 100644 --- a/doc/manual/compile.xml +++ b/doc/manual/compile.xml @@ -1,61 +1,51 @@ + + 2024-06-01 + Compile Netatalk from Source Overview - - This section describes how to compile Netatalk from source for specific operating systems. - - - The Netatalk project is in the process of transitioning the build system - from GNU Autotools to Meson. - During the transitional period, - the documentation will contain both Autotools and Meson build instructions. - - - Please note that this document is automatically generated from the GitHub workflow YAML file. - This may or may not be the most optimal way to build Netatalk for your system. - + This appendix describes how to compile Netatalk from source for specific operating systems. + Please note that the steps below are automatically generated, and may not be optimized for your system. + Choose one of the build systems: Autotools or Meson. Test steps are optional. Operating Systems - - Note: You only have to use execute the steps for one of the build systems, not both. - Additionally, the test steps are entirely optional for compiling from source. - - - Ubuntu + + Alpine Linux Install dependencies - sudo apt-get update -sudo apt-get install --assume-yes --no-install-recommends autoconf \ -automake \ -docbook-xsl \ -libacl1-dev \ -libavahi-client-dev \ -libcrack2-dev \ -libcups2-dev \ -libdb-dev \ -libgcrypt-dev \ -libkrb5-dev \ -libldap2-dev \ -libltdl-dev \ -libpam0g-dev \ -libssl-dev \ -libtirpc-dev \ -libtool \ -libtool-bin \ -libwrap0-dev \ -meson \ -ninja-build \ -quota \ -tcpd \ -xsltproc - + apk add \ + acl-dev \ + autoconf \ + automake \ + avahi-dev \ + build-base \ + cracklib \ + cracklib-dev \ + cracklib-words \ + cups \ + cups-dev \ + curl \ + db-dev \ + gcc \ + krb5-dev \ + libgcrypt-dev \ + libtirpc-dev \ + libtool \ + linux-pam-dev \ + meson \ + ninja \ + openldap-dev \ + openrc \ + openssl-dev \ + pkgconfig \ + rpcsvc-proto-dev Autotools - Bootstrap @@ -66,60 +56,54 @@ xsltproc ./configure \ --enable-krbV-uam \ + --enable-openrc \ --enable-pgp-uam \ - --enable-quota \ - --enable-systemd \ --with-cracklib \ --with-libtirpc - Autotools - Generate manual pages - - make html - Autotools - Build - make -j $(nproc) all + make -j $(nproc) Autotools - Run tests make check - Autotools - Run distribution tests + Autotools - Install - make distcheck + make install - Autotools - Install + Autotools - Uninstall - sudo make install + make uninstall Meson - Configure meson setup build \ -Dbuild-tests=true \ - -Dbuild-manual=true \ - -Dwith-libtirpc=true + -Denable-openrc=true - Meson - Build and generate man pages + Meson - Build ninja -C build - Meson - Tests + Meson - Run tests cd build && meson test - Meson - Distribution tests + Meson - Install - cd build && meson dist + ninja -C build install - Meson - Install + Meson - Uninstall - sudo ninja -C build install + ninja -C build uninstall - Debian + Debian Linux Install dependencies apt-get update @@ -176,6 +160,10 @@ xsltproc make install + Autotools - Uninstall + + make uninstall + Meson - Configure meson setup build \ @@ -196,12 +184,16 @@ xsltproc ninja -C build install + Meson - Uninstall + + ninja -C build uninstall + - Fedora + Fedora Linux Install dependencies - dnf -y install \ + dnf --setopt=install_weak_deps=False --assumeyes install \ automake \ avahi-devel \ chkconfig \ @@ -228,7 +220,7 @@ xsltproc ./configure \ --enable-pgp-uam \ --enable-krbV-uam \ - --enable-redhat-sysv \ + --enable-redhat \ --with-cracklib=/usr/share/cracklib @@ -244,12 +236,16 @@ xsltproc sudo make install + Autotools - Uninstall + + sudo make uninstall + Meson - Configure meson setup build \ -Dbuild-tests=true \ -Dwith-libtirpc=true \ - -Denable-redhat-sysv=true + -Denable-redhat=true Meson - Build @@ -264,12 +260,16 @@ xsltproc sudo ninja -C build install + Meson - Uninstall + + sudo ninja -C build uninstall + macOS Install dependencies - brew install automake libressl krb5 berkeley-db meson + brew install automake berkeley-db krb5 libressl libtool meson Autotools - Bootstrap @@ -279,10 +279,11 @@ xsltproc ./configure \ --disable-ddp \ - --enable-pgp-uam \ --enable-krbV-uam \ - --with-ssl-dir=/usr/local/opt/libressl \ - --with-bdb=/usr/local/opt/berkeley-db + --enable-macos \ + --enable-pgp-uam \ + --with-bdb=/opt/homebrew/opt/berkeley-db \ + --with-ssl-dir=/opt/homebrew/opt/libressl Autotools - Build @@ -297,13 +298,24 @@ xsltproc sudo make install + Start netatalk + + sudo netatalkd start && sleep 2 && asip-status localhost + + Stop netatalk + + sudo netatalkd stop + + Autotools - Uninstall + + sudo make uninstall + Meson - Configure meson setup build \ - -Dwith-bdb=/usr/local/opt/berkeley-db \ - -Dwith-ssl-dir=/usr/local/opt/libressl \ -Dbuild-tests=true \ - -Denable-macos=true + -Denable-macos=true \ + -Dwith-bdb=/opt/homebrew/opt/berkeley-db Meson - Build @@ -318,10 +330,22 @@ xsltproc sudo ninja -C build install + Start netatalk + + sudo netatalkd start && sleep 2 && asip-status localhost + + Stop netatalk + + sudo netatalkd stop + + Meson - Uninstall + + sudo ninja -C build uninstall + NetBSD - Install dependencies + Install required packages pkg_add \ autoconf \ @@ -352,20 +376,122 @@ echo "Building with Autotools" MAKE=gmake \ PKG_CONFIG_PATH=/usr/pkg/lib/pkgconfig gmake -j2 all +gmake install +service afpd onestart +sleep 2 +asip-status localhost +service afpd onestop echo "Building with Meson" meson setup build \ -Dpkg_config_path=/usr/pkg/lib/pkgconfig \ -Denable-netbsd=true ninja -C build ninja -C build install +service afpd onestart +sleep 2 +asip-status localhost +service afpd onestop +ninja -C build uninstall + + + + + openSUSE Linux + Install dependencies + + zypper in -y \ + automake \ + file \ + gawk \ + gcc \ + libtool \ + make \ + meson \ + ninja \ + pkg-config \ + systemd \ + wget && +zypper in -y \ + cracklib-devel \ + glib2-devel \ + krb5-devel \ + libacl-devel \ + libavahi-devel \ + libdb-4_8-devel \ + libgcrypt-devel \ + libmariadb-devel \ + libopenssl-devel \ + libtdb-devel \ + openldap2-devel \ + pam-devel \ + systemtap-sdt-devel \ + tcpd-devel + + + Autotools - Bootstrap + + ./bootstrap + + Autotools - Configure + + ./configure \ + --disable-install-privileged \ + --enable-krbV-uam \ + --enable-pgp-uam \ + --with-cracklib \ + --enable-systemd + + + Autotools - Build + + make -j $(nproc) + + Autotools - Run tests + + make check + + Autotools - Install + + make install + + Autotools - Uninstall + + make uninstall + + Meson - Configure + + meson setup build \ + -Dbuild-tests=true + Meson - Build + + ninja -C build + + Meson - Run tests + + cd build && meson test + + Meson - Install + + ninja -C build install + + Meson - Uninstall + + ninja -C build uninstall + Solaris - Install dependencies + Install required packages - pkg install autoconf automake libtool pkg-config gcc libgcrypt + pkg install \ + autoconf \ + automake \ + gcc \ + libgcrypt \ + libtool \ + pkg-config wget https://ftp.gnu.org/gnu/autoconf/autoconf-2.71.tar.gz --no-check-certificate wget https://ftp.gnu.org/gnu/automake/automake-1.16.5.tar.gz --no-check-certificate tar xvf autoconf-2.71.tar.gz @@ -378,7 +504,7 @@ cd ../automake-1.16.5 ./configure --prefix=/usr make make install -cd .. +cd .. Configure and build @@ -391,8 +517,126 @@ echo "Building with Autotools" --enable-cups=no gmake -j $(nproc) all gmake install +gmake uninstall + + + + + Ubuntu Linux + Install dependencies + + sudo apt-get update +sudo apt-get install --assume-yes --no-install-recommends autoconf \ +automake \ +docbook-xsl \ +libacl1-dev \ +libavahi-client-dev \ +libcrack2-dev \ +libcups2-dev \ +libdb-dev \ +libgcrypt-dev \ +libkrb5-dev \ +libldap2-dev \ +libltdl-dev \ +libpam0g-dev \ +libssl-dev \ +libtirpc-dev \ +libtool \ +libtool-bin \ +libwrap0-dev \ +meson \ +ninja-build \ +quota \ +tcpd \ +xsltproc + + + + Autotools - Bootstrap + + ./bootstrap + + Autotools - Configure + + ./configure \ + --enable-krbV-uam \ + --enable-pgp-uam \ + --enable-quota \ + --enable-systemd \ + --with-cracklib \ + --with-libtirpc + + + Autotools - Generate manual pages + + make html + + Autotools - Build + + make -j $(nproc) all + + Autotools - Run tests + + make check + + Autotools - Run distribution tests + + make distcheck + + Autotools - Install + + sudo make install + + Start netatalk + + sudo systemctl start afpd && sleep 2 && asip-status localhost + + Stop netatalk + + sudo systemctl stop afpd + + Autotools - Uninstall + + sudo make uninstall + + Meson - Configure + + meson setup build \ + -Dbuild-tests=true \ + -Dbuild-manual=true \ + -Ddisable-install-privileged=true \ + -Denable-systemd=true \ + -Dwith-libtirpc=true + Meson - Build and generate man pages + + ninja -C build + + Meson - Tests + + cd build && meson test + + Meson - Distribution tests + + cd build && meson dist + + Meson - Install + + sudo ninja -C build install + + Start netatalk + + sudo systemctl start afpd && sleep 2 && asip-status localhost + + Stop netatalk + + sudo systemctl stop afpd + + Meson - Uninstall + + sudo ninja -C build uninstall + diff --git a/doc/manual/meson.build b/doc/manual/meson.build index 3c3829d3f7..9c68f1f0c8 100644 --- a/doc/manual/meson.build +++ b/doc/manual/meson.build @@ -4,9 +4,9 @@ manual_xml = configure_file( configuration: cdata, ) -netatalk_html = configure_file( - input: 'netatalk.html.in', - output: 'netatalk.html', +pageheader = configure_file( + input: 'pageheader.txt.in', + output: 'pageheader.txt', configuration: cdata, ) diff --git a/doc/manual/netatalk.html.in b/doc/manual/pageheader.txt.in similarity index 100% rename from doc/manual/netatalk.html.in rename to doc/manual/pageheader.txt.in diff --git a/doc/manual/requirements.txt b/doc/requirements.txt similarity index 100% rename from doc/manual/requirements.txt rename to doc/requirements.txt