From 6971aed95db412841443abf5ff566a4e704e67e6 Mon Sep 17 00:00:00 2001 From: Marian Koncek Date: Jul 16 2024 16:34:03 +0000 Subject: [PATCH 1/3] OCaml guidelines: fix unordered and nested lists --- diff --git a/guidelines/modules/ROOT/pages/OCaml.adoc b/guidelines/modules/ROOT/pages/OCaml.adoc index 565a9eb..7c262d6 100644 --- a/guidelines/modules/ROOT/pages/OCaml.adoc +++ b/guidelines/modules/ROOT/pages/OCaml.adoc @@ -148,12 +148,13 @@ This is because OCaml scripts are recompiled each time they run. == RPM Macros The following macros are available to use in spec files: + * `%{ocaml_native_compiler}`: the architectures for which native compilation is available * `%{ocaml_natdynlink}`: the architectures for which native dynamic linking is available * `%{ocamldir}`: top-level installation directory for OCaml packages, currently equivalent to `%{_libdir}/ocaml` * `%{ocaml_files}`: generate a list of installed files, in files named .ofiles (for the main package) and .ofiles-devel (for the devel subpackage), unless `-s` or `-n` is given. This macro requires that python3 be available in the buildroot. Flags: - * -n: there is no devel subpackage. All files are listed in .ofiles. - * -s: separate installation; each subdirectory of `%{ocamldir}` is a separate RPM package. For each subdirectory, `.ofiles-` and `.ofiles--devel` is generated (unless `-n` is also given). +** -n: there is no devel subpackage. All files are listed in .ofiles. +** -s: separate installation; each subdirectory of `%{ocamldir}` is a separate RPM package. For each subdirectory, `.ofiles-` and `.ofiles--devel` is generated (unless `-n` is also given). == Examples @@ -163,20 +164,21 @@ This section contains example spec files illustrating how to build OCaml library Dune is a popular build tool for OCaml packages. RPM macros are available to make building with dune simple. + * `%dune_build`: Invoke dune to build all installable artifacts in release mode. Flags: - * -j : number of jobs that can be run in parallel. This is automatically set to `%{?_smp_mflags}`, so is typically used only to eliminate parallelism with `-j 1`. - * -p : tell dune to build the comma-separated list of modules only, rather than every installable artifact. - * --: separate flags for this macro from flags to pass to dune +** -j : number of jobs that can be run in parallel. This is automatically set to `%{?_smp_mflags}`, so is typically used only to eliminate parallelism with `-j 1`. +** -p : tell dune to build the comma-separated list of modules only, rather than every installable artifact. +** --: separate flags for this macro from flags to pass to dune * `%dune_install`: Invoke dune to install all installable artifacts. Flags: - * -n: there is no devel subpackage. All files are associated with the main package. - * -s: separate installation; each subdirectory of `%{ocamldir}` is a separate RPM package. Otherwise, all files are associated with a single main package. - * --: separate flags for this macro from flags to pass to dune +** -n: there is no devel subpackage. All files are associated with the main package. +** -s: separate installation; each subdirectory of `%{ocamldir}` is a separate RPM package. Otherwise, all files are associated with a single main package. +** --: separate flags for this macro from flags to pass to dune * `%dune_check`: Invoke dune to run tests for all installable artifacts. Flags: - * -j : number of jobs that can be run in parallel. This is automatically set to `%{?_smp_mflags}`, so is typically used only to eliminate parallelism with `-j 1`. - * -p : tell dune to build the comma-separated list of modules only, rather than every installable artifact. - * --: separate flags for this macro from flags to pass to dune +** -j : number of jobs that can be run in parallel. This is automatically set to `%{?_smp_mflags}`, so is typically used only to eliminate parallelism with `-j 1`. +** -p : tell dune to build the comma-separated list of modules only, rather than every installable artifact. +** --: separate flags for this macro from flags to pass to dune * `%odoc_package`: Declare a subpackage that olds odoc-generated documentation. Flags: - * -L : give the name of a file to include in the subpackage as a license file. +** -L : give the name of a file to include in the subpackage as a license file. The following is an example specfile for an imaginary OCaml library called _foolib_ that is built with dune. From 237094dd8e620680801ae93b14429a6c4b9947a7 Mon Sep 17 00:00:00 2001 From: Marian Koncek Date: Jul 16 2024 16:47:12 +0000 Subject: [PATCH 2/3] OCaml guidelines: use monospace fonts much more --- diff --git a/guidelines/modules/ROOT/pages/OCaml.adoc b/guidelines/modules/ROOT/pages/OCaml.adoc index 7c262d6..c1d1f59 100644 --- a/guidelines/modules/ROOT/pages/OCaml.adoc +++ b/guidelines/modules/ROOT/pages/OCaml.adoc @@ -8,10 +8,10 @@ It does not intend to cover all situations, but to codify those practices which The base OCaml compiler is called ocaml. OCaml modules, libraries and syntax extensions should be named ocaml-foo. -Examples include: ocaml-extlib, ocaml-ssl. +Examples include: `ocaml-extlib`, `ocaml-ssl`. This naming does not apply to applications written in OCaml, which can be given their normal name. -Examples include: coccinelle, frama-c, virt-top. +Examples include: `coccinelle`, `frama-c`, `virt-top`. Rationale: this is how they are named in other distros (Debian, PLD) and this is consistent with Perl / PHP / Python naming. @@ -21,72 +21,73 @@ Rationale: this is how they are named in other distros (Debian, PLD) and this is In order to allow OCaml scripts and the toplevel to use a library, the main package should contain only files matching: -* *.cma (contains the bytecode) -* *.cmi (contains the compiled signature) -* *.so (if present, contains OCaml <-> C stubs) -* META (the findlib description) -* *.so.owner (if present, used by findlib) -* a license file (if present) marked %license +* `*.cma` (contains the bytecode) +* `*.cmi` (contains the compiled signature) +* `*.so` (if present, contains OCaml <-> C stubs) +* `META` (the findlib description) +* `*.so.owner` (if present, used by findlib) +* a license file (if present) marked `%license` -* .cmo files are not normally included. There is one exception where *.cmo files may be included: if the cmo file is needed to link, then it must be included to allow the library to be linked properly. +* `.cmo` files are not normally included. There is one exception where `*.cmo` files may be included: if the `.cmo` file is needed to link, then it must be included to allow the library to be linked properly. -If the package contains *.so files, then they should not have rpaths, as per Fedora packaging guidelines. +If the package contains `*.so` files, then they should not have rpaths, as per Fedora packaging guidelines. -The packager should check the META file footnote:[http://projects.camlcity.org/projects/dl/findlib-1.9.5/doc/ref-html/r759.html[findlib Reference Manual - META files.]]. -If there is no META file, then the packager should create one, include it in the package, and pass it to the upstream maintainer. +The packager should check the `META` file footnote:[http://projects.camlcity.org/projects/dl/findlib-1.9.5/doc/ref-html/r759.html[findlib Reference Manual - META files.]]. +If there is no `META` file, then the packager should create one, include it in the package, and pass it to the upstream maintainer. Rationale: OCaml does not support dynamic linking of binaries, and even if it did with the current module hash system for expressing strict typing requirements almost any conceivable change to a library would require the binary to be recompiled. OCaml scripts are the closest we come to dynamic linking, in as much as they do not usually depend on a specific version of a library (albeit this only works because the scripts are recompiled each time they run). -=== -devel subpackage +=== `-devel` subpackage -The -devel subpackage of a library should contain all other files required to allow development with the library. Normally these would be: +The `-devel` subpackage of a library should contain all other files required to allow development with the library. Normally these would be: -* *.a (contains the compiled machine code) -* *.cmxa (describes the compiled machine code) -* *.cmx (if present, allows cross-module optimizations) -* *.mli (contains the signature of the library) +* `*.a` (contains the compiled machine code) +* `*.cmxa` (describes the compiled machine code) +* `*.cmx` (if present, allows cross-module optimizations) +* `*.mli` (contains the signature of the library) -* .o files are not normally included. There is one exception -- if the file is needed to link (like std_exit.cmx and std_exit.o in OCaml itself), then it should be included. +* `.o` files are not normally included. There is one exception -- if the file is needed to link (like `std_exit.cmx` and `std_exit.o` in OCaml itself), then it should be included. -* .ml files are not normally included. The exception is if the file describes a module signature _and_ there is no corresponding .mli file, then the .ml file should be included. (Note that Debian is more permissive and they often distribute *.ml files, allowing the programmer to peek at the implementation of a module). +* `.ml` files are not normally included. The exception is if the file describes a module signature _and_ there is no corresponding `.mli` file, then the `.ml` file should be included. (Note that Debian is more permissive and they often distribute `*.ml` files, allowing the programmer to peek at the implementation of a module). -Documentation, examples and other articles which are useful to the developer may be included in the -devel sub-package. -The license file (which is in the main package) does not need to be included again in the -devel subpackage. +Documentation, examples and other articles which are useful to the developer may be included in the `-devel` sub-package. +The license file (which is in the main package) does not need to be included again in the `-devel` subpackage. -If the -devel subpackage would only contain documentation files, then the packager may at their discretion place the documentation files in the main package and not have a -devel subpackage at all. +If the `-devel` subpackage would only contain documentation files, then the packager may at their discretion place the documentation files in the main package and not have a `-devel` subpackage at all. -The -devel subpackage should require the exact name-version-release of the main package (as per Fedora policy). -It should also require any C libraries required for development, and sometimes this means an explicit 'Requires' is needed. -For example, ocaml-pcre-devel needs an explicit 'Requires: pcre-devel' to make it usable for development. +The `-devel` subpackage should require the exact name-version-release of the main package (as per Fedora policy). +It should also require any C libraries required for development, and sometimes this means an explicit `Requires` is needed. +For example, `ocaml-pcre-devel` needs an explicit `Requires: pcre-devel` to make it usable for development. -Rationale for inclusion of all cmx files: [*.cmx files] are needed even for modules included in .cmxa libraries in order to enable cross-module optimizations (inlining, constant propagation and direct function calls). -The .o files are not needed. [From a private email from Alain Frisch] +Rationale for inclusion of all `.cmx` files: these files are needed even for modules included in `.cmxa` libraries in order to enable cross-module optimizations (inlining, constant propagation and direct function calls). +The `.o` files are not needed. [From a private email from Alain Frisch] -=== -doc subpackage +=== `-doc` subpackage If the documentation files are very large they may be placed in a -separate -doc subpackage, as per normal Fedora guidelines. +separate `-doc` subpackage, as per normal Fedora guidelines. -=== -data subpackage +=== `-data` subpackage If the package contains excessively large data files, they may -be placed in a separate -data subpackage, as per normal Fedora guidelines. +be placed in a separate `-data` subpackage, as per normal Fedora guidelines. -=== Requires and provides +=== `Requires` and `Provides` -For each module that library A uses from another library B, library A must have a Requires of the form: -ocaml(Modulename) = MD5hash -Similarly for each module that library A may provide to other libraries, library A must have a Provides of the same form. +For each module that library `A` uses from another library `B`, library `A` must have a `Requires` of the form: +`ocaml(Modulename) = MD5hash` + +Similarly for each module that library `A` may provide to other libraries, library `A` must have a `Provides` of the same form. A library must depend on the precise version of the OCaml compiler, for example: -ocaml(runtime) = 3.10.0 +`ocaml(runtime) = 3.10.0` -The correct Requires and Provides should be generated automatically. +The correct `Requires` and `Provides` should be generated automatically. Rationale: OCaml does not offer binary compatibility between releases of the compiler (even between bugfixes). Furthermore the module system uses a hash over the interface and some internals of a module which basically means a library or program must be linked against the identical modules it was compiled with. -The Requires and Provides lines express the module name and hash so that RPM enforces the same requirements as the OCaml linker itself. +The `Requires` and `Provides` lines express the module name and hash so that RPM enforces the same requirements as the OCaml linker itself. Please see the further reading at the end of this page for more details. == Packaging binaries @@ -101,7 +102,7 @@ Binaries should be stripped, as per ordinary Fedora packaging guidelines. There is one exception where a binary should not be stripped. If the package was compiled with `ocamlc -custom` then the package contains bytecode which strip will remove, thus rendering the binary inoperable. -It is easy to test for this: if after stripping, any attempt to run the binary results in the message _No bytecode file specified_ then the binary is compiled like this and should not be stripped. +It is easy to test for this: if after stripping, any attempt to run the binary results in the message `No bytecode file specified` then the binary is compiled like this and should not be stripped. Rationale: https://bugs.debian.org/256900 @@ -111,7 +112,7 @@ The packager should attempt to ship native code compiled binaries in preference == Bytecode-only architectures -The OCaml native code compiler (ocamlopt) contains code generators for popular architectures, but not for every architecture that Fedora might support. +The OCaml native code compiler (`ocamlopt`) contains code generators for popular architectures, but not for every architecture that Fedora might support. On such architectures, the spec file should still build bytecode libraries and binaries. To test for presence of the native compiler, use the `%{ocaml_native_compiler}` macro. @@ -126,7 +127,7 @@ make opt %endif .... -To test that your spec file will work on such an architecture, temporarily remove or rename /usr/bin/ocamlopt and /usr/bin/ocamlopt.opt while building. +To test that your spec file will work on such an architecture, temporarily remove or rename `/usr/bin/ocamlopt` and `/usr/bin/ocamlopt.opt` while building. Rationale: Debian packaging policy section 2.3 does the same thing. @@ -134,9 +135,9 @@ Rationale: Debian packaging policy section 2.3 does the same thing. The following files should not normally be distributed: -* *.cmo object files. Exception: see above. -* *.o for corresponding *.cmx. Exception: see above. -* *.ml sources. Exception: see above. +* `*.cmo` object files. Exception: see above. +* `*.o` for corresponding `*.cmx`. Exception: see above. +* `*.ml` sources. Exception: see above. == Security issues in OCaml libraries @@ -152,9 +153,9 @@ The following macros are available to use in spec files: * `%{ocaml_native_compiler}`: the architectures for which native compilation is available * `%{ocaml_natdynlink}`: the architectures for which native dynamic linking is available * `%{ocamldir}`: top-level installation directory for OCaml packages, currently equivalent to `%{_libdir}/ocaml` -* `%{ocaml_files}`: generate a list of installed files, in files named .ofiles (for the main package) and .ofiles-devel (for the devel subpackage), unless `-s` or `-n` is given. This macro requires that python3 be available in the buildroot. Flags: -** -n: there is no devel subpackage. All files are listed in .ofiles. -** -s: separate installation; each subdirectory of `%{ocamldir}` is a separate RPM package. For each subdirectory, `.ofiles-` and `.ofiles--devel` is generated (unless `-n` is also given). +* `%{ocaml_files}`: generate a list of installed files, in files named `.ofiles` (for the main package) and .ofiles-devel (for the devel subpackage), unless `-s` or `-n` is given. This macro requires that python3 be available in the buildroot. Flags: +** `-n`: there is no devel subpackage. All files are listed in `.ofiles`. +** `-s`: separate installation; each subdirectory of `%{ocamldir}` is a separate RPM package. For each subdirectory, `.ofiles-` and `.ofiles--devel` is generated (unless `-n` is also given). == Examples @@ -166,21 +167,21 @@ Dune is a popular build tool for OCaml packages. RPM macros are available to make building with dune simple. * `%dune_build`: Invoke dune to build all installable artifacts in release mode. Flags: -** -j : number of jobs that can be run in parallel. This is automatically set to `%{?_smp_mflags}`, so is typically used only to eliminate parallelism with `-j 1`. -** -p : tell dune to build the comma-separated list of modules only, rather than every installable artifact. -** --: separate flags for this macro from flags to pass to dune +** `-j `: number of jobs that can be run in parallel. This is automatically set to `%{?_smp_mflags}`, so is typically used only to eliminate parallelism with `-j 1`. +** `-p `: tell dune to build the comma-separated list of modules only, rather than every installable artifact. +** `--`: separate flags for this macro from flags to pass to dune * `%dune_install`: Invoke dune to install all installable artifacts. Flags: -** -n: there is no devel subpackage. All files are associated with the main package. -** -s: separate installation; each subdirectory of `%{ocamldir}` is a separate RPM package. Otherwise, all files are associated with a single main package. -** --: separate flags for this macro from flags to pass to dune +** `-n`: there is no devel subpackage. All files are associated with the main package. +** `-s`: separate installation; each subdirectory of `%{ocamldir}` is a separate RPM package. Otherwise, all files are associated with a single main package. +** `--`: separate flags for this macro from flags to pass to dune * `%dune_check`: Invoke dune to run tests for all installable artifacts. Flags: -** -j : number of jobs that can be run in parallel. This is automatically set to `%{?_smp_mflags}`, so is typically used only to eliminate parallelism with `-j 1`. -** -p : tell dune to build the comma-separated list of modules only, rather than every installable artifact. -** --: separate flags for this macro from flags to pass to dune +** `-j `: number of jobs that can be run in parallel. This is automatically set to `%{?_smp_mflags}`, so is typically used only to eliminate parallelism with `-j 1`. +** `-p `: tell dune to build the comma-separated list of modules only, rather than every installable artifact. +** `--`: separate flags for this macro from flags to pass to dune * `%odoc_package`: Declare a subpackage that olds odoc-generated documentation. Flags: -** -L : give the name of a file to include in the subpackage as a license file. +** `-L `: give the name of a file to include in the subpackage as a license file. -The following is an example specfile for an imaginary OCaml library called _foolib_ that is built with dune. +The following is an example specfile for an imaginary OCaml library called _foolib_ that is built with `dune`. .ocaml-dune-example.spec [source] @@ -188,11 +189,11 @@ The following is an example specfile for an imaginary OCaml library called _fool include::{examplesdir}/ocaml-dune-example.spec[] ---- -=== Topkg +=== `Topkg` -Topkg, the "transitory OCaml software packager", generates scripts that are executed to perform various package and build tasks. +`topkg`, the "transitory OCaml software packager", generates scripts that are executed to perform various package and build tasks. -The following is an example specfile for an imaginary OCaml library called _foolib_ that is built with topkg. +The following is an example specfile for an imaginary OCaml library called _foolib_ that is built with `topkg`. .ocaml-topkg-example.spec [source] From 7711c04bbf241cb313dbc27e472138963b555ee6 Mon Sep 17 00:00:00 2001 From: Marian Koncek Date: Jul 16 2024 16:47:36 +0000 Subject: [PATCH 3/3] OCaml guidelines: use one sentence per line --- diff --git a/guidelines/modules/ROOT/pages/OCaml.adoc b/guidelines/modules/ROOT/pages/OCaml.adoc index c1d1f59..12914b0 100644 --- a/guidelines/modules/ROOT/pages/OCaml.adoc +++ b/guidelines/modules/ROOT/pages/OCaml.adoc @@ -65,13 +65,11 @@ The `.o` files are not needed. [From a private email from Alain Frisch] === `-doc` subpackage -If the documentation files are very large they may be placed in a -separate `-doc` subpackage, as per normal Fedora guidelines. +If the documentation files are very large they may be placed in a separate `-doc` subpackage, as per normal Fedora guidelines. === `-data` subpackage -If the package contains excessively large data files, they may -be placed in a separate `-data` subpackage, as per normal Fedora guidelines. +If the package contains excessively large data files, they may be placed in a separate `-data` subpackage, as per normal Fedora guidelines. === `Requires` and `Provides`