diff options
Diffstat (limited to 'dev/doc')
| -rw-r--r-- | dev/doc/MERGING.md | 4 | ||||
| -rw-r--r-- | dev/doc/build-system.dune.md | 57 | ||||
| -rw-r--r-- | dev/doc/changes.md | 86 | ||||
| -rw-r--r-- | dev/doc/profiling.txt | 2 | ||||
| -rw-r--r-- | dev/doc/release-process.md | 30 |
5 files changed, 126 insertions, 53 deletions
diff --git a/dev/doc/MERGING.md b/dev/doc/MERGING.md index c0cd9c8cdd..000f21c254 100644 --- a/dev/doc/MERGING.md +++ b/dev/doc/MERGING.md @@ -54,7 +54,7 @@ those external projects should have been prepared (cf. the relevant sub-section in the [CI README](../ci/README.md#Breaking-changes) and the PR can be tested with these fixes thanks to ["overlays"](../ci/user-overlays/README.md). -Moreover the PR must absolutely update the [`CHANGES`](../../CHANGES) file. +Moreover the PR must absolutely update the [`CHANGES.md`](../../CHANGES.md) file. If overlays are missing, ask the author to prepare them and label the PR with the [needs: overlay](https://github.com/coq/coq/labels/needs%3A%20overlay) label. @@ -93,7 +93,7 @@ When the PR has conflicts, the assignee can either: In both cases, CI should be run again. -In some rare cases (e.g. the conflicts are in the CHANGES file), it is ok to fix +In some rare cases (e.g. the conflicts are in the `CHANGES.md` file), it is ok to fix the conflicts in the merge commit (following the same steps as below), and push to `master` directly. Don't use the GitHub interface to fix these conflicts. diff --git a/dev/doc/build-system.dune.md b/dev/doc/build-system.dune.md index 85aaf317ef..7349360be8 100644 --- a/dev/doc/build-system.dune.md +++ b/dev/doc/build-system.dune.md @@ -3,29 +3,45 @@ Dune-based build system. If you want to enhance the build system itself (or are curious about its implementation details), see build-system.dev.txt, and in particular its initial HISTORY section. -Dune -==== +About Dune +========== -Coq can now be built using -[Dune](https://github.com/ocaml/dune). Contrary to other systems, -Dune, doesn't use a global`makefile` but local build files named -`dune` that are later composed to form a global build. +Coq can now be built using [Dune](https://github.com/ocaml/dune). + +## Quick Start + +You need Dune >= 1.2.1 ; just type `dune build` to build the base Coq +libraries. No call to `./configure` is needed. + +Dune will get confused if it finds leftovers of in-tree compilation, +so please be sure your tree is clean from objects files generated by +the make-based system. + +If you want to build the standard libraries and plugins you should +call `make -f Makefile.dune voboot`. It is usually enough to do that +once per-session. + +More helper targets are availabe in `Makefile.dune`, `make -f +Makefile.dune` will display some help. + +Dune places build artifacts in a separate directory `_build`; it will +also generate an `.install` file so files can be properly installed by +package managers. + +Contrary to other systems, Dune doesn't use a global `Makefile` but +local build files named `dune` that are later composed to form a +global build. As a developer, Dune should take care of all OCaml-related build tasks -including library management, merlin files, and link order. You are +including library management, merlin files, and linking order. You are are not supposed to modify the `dune` files unless you are adding a new binary, library, or plugin. -The current Dune setup also doesn't require a call to `configure`. The -auto-generated configuration files are properly included in the -dependency graph so it will be automatically generated by Dune with -reasonable developer defaults. You can still override the defaults by -manually calling `./configure`, but note that some configure options -such as install paths are not used by Dune. +## Per-User Custom Settings -Dune uses a separate directory `_build` to store build artifacts; it -will generate an `.install` file so artifacts in the build can be -properly installed by package managers. +Dune will read the file `~/.config/dune/config`; see `man +dune-config`. Among others, you can set in this file the custom number +of build threads `(jobs N)` and display options `(display _mode_)`. ## Targets @@ -36,8 +52,10 @@ project, creating an "install" overlay in `_build/install/default`. You can build some other target by doing `dune build $TARGET`. In order to build a single package, you can do `dune build -$PACKAGE.install`. Dune also provides targets for documentation and -testing, see below. +$PACKAGE.install`. + +Dune also provides targets for documentation, testing, and release +builds, please see below. ## Developer shell @@ -66,7 +84,8 @@ current Coq source tree contains two packages [Coq and CoqIDE], and in the OPAM CoqIDE package we don't want to build CoqIDE against the local copy of Coq. For this purpose, Dune supports the `-p` option, so `dune build -p coqide` will build CoqIDE against the system-installed -version of Coq libs. +version of Coq libs, and use a "release" profile that for example +enables stronger compiler optimizations. ## Stanzas diff --git a/dev/doc/changes.md b/dev/doc/changes.md index 4f3d793ed4..7e64f80ac5 100644 --- a/dev/doc/changes.md +++ b/dev/doc/changes.md @@ -1,3 +1,24 @@ +## Changes between Coq 8.9 and Coq 8.10 + +### ML API + +General deprecation + +- All functions marked [@@ocaml.deprecated] in 8.8 have been + removed. Please, make sure your plugin is warning-free in 8.8 before + trying to port it over 8.9. + +Names + +- Kernel names no longer contain a section path. They now have only two + components (module path and label), which led to some changes in the API: + + KerName.make takes only 2 components + KerName.repr returns only 2 components + KerName.make2 is now KerName.make + Constant.make3 has been removed, use Constant.make2 + Constant.repr3 has been removed, use Constant.repr2 + ## Changes between Coq 8.8 and Coq 8.9 ### ML API @@ -7,8 +28,8 @@ Names - In `Libnames`, the type `reference` and its two constructors `Qualid` and `Ident` have been removed in favor of `qualid`. `Qualid` is now the identity, `Ident` can be replaced by `qualid_of_ident`. Matching over `reference` can be - replaced by a test using `qualid_is_ident`. Extracting the ident part of a - qualid can be done using `qualid_basename`. + replaced by a test using `qualid_is_ident`. Extracting the `ident` part of a + `qualid` can be done using `qualid_basename`. Misctypes @@ -42,20 +63,20 @@ Proof engine ML Libraries used by Coq -- Introduction of a "Smart" module for collecting "smart*" functions, e.g. - Array.Smart.map. -- Uniformization of some names, e.g. Array.Smart.fold_left_map instead - of Array.smartfoldmap. +- Introduction of a `Smart` module for collecting `smart*` functions, e.g. + `Array.Smart.map`. +- Uniformization of some names, e.g. `Array.Smart.fold_left_map` instead + of `Array.smartfoldmap`. Printer.ml API -- The mechanism in Printer that allowed dynamically overriding pr_subgoals, - pr_subgoal and pr_goal was removed to simplify the code. It was - earlierly used by PCoq. +- The mechanism in `Printer` that allowed dynamically overriding `pr_subgoals`, + `pr_subgoal` and `pr_goal` was removed to simplify the code. It was + earlier used by PCoq. Kernel - The following renamings happened: +- The following renamings happened: - `Context.Rel.t` into `Constr.rel_context` - `Context.Named.t` into `Constr.named_context` - `Context.Compacted.t` into `Constr.compacted_context` @@ -84,19 +105,24 @@ Vernacular commands Primitive number parsers -- For better modularity, the primitive parsers for positive, N and Z - have been split over three files (plugins/syntax/positive_syntax.ml, - plugins/syntax/n_syntax.ml, plugins/syntax/z_syntax.ml). +- For better modularity, the primitive parsers for `positive`, `N` and `Z` + have been split over three files (`plugins/syntax/positive_syntax.ml`, + `plugins/syntax/n_syntax.ml`, `plugins/syntax/z_syntax.ml`). Parsing -- Manual uses of the Pcoq.Gram module have been deprecated. Wrapper modules - Pcoq.Entry and Pcoq.Parsable were introduced to replace it. +- Manual uses of the `Pcoq.Gram` module have been deprecated. Wrapper modules + `Pcoq.Entry` and `Pcoq.Parsable` were introduced to replace it. + +Termops + +- Internal printing functions have been placed under the + `Termops.Internal` namespace. ### Unit testing - The test suite now allows writing unit tests against OCaml code in the Coq - code base. Those unit tests create a dependency on the OUnit test framework. +The test suite now allows writing unit tests against OCaml code in the Coq +code base. Those unit tests create a dependency on the OUnit test framework. ### Transitioning away from Camlp5 @@ -131,7 +157,7 @@ let myval = 0 Steps to perform: - replace the brackets enclosing OCaml code in actions with braces -- if not there yet, add a leading `|̀ to the first rule +- if not there yet, add a leading `|` to the first rule For instance, code of the form: ``` @@ -162,8 +188,8 @@ Most plugin writers do not need this low-level interface, but for the sake of completeness we document it. Steps to perform are: -- replace GEXTEND with GRAMMAR EXTEND -- wrap every occurrence of OCaml code in actions into braces { } +- replace `GEXTEND` with `GRAMMAR EXTEND` +- wrap every occurrence of OCaml code in actions into braces `{ }` For instance, code of the form ``` @@ -213,7 +239,7 @@ All the other bugs kept their number. General deprecation -- All functions marked [@@ocaml.deprecated] in 8.7 have been +- All functions marked `[@@ocaml.deprecated]` in 8.7 have been removed. Please, make sure your plugin is warning-free in 8.7 before trying to port it over 8.8. @@ -241,8 +267,8 @@ We changed the type of the following functions: - `Global.body_of_constant`: same as above. -- `Constrinterp.*` generally, many functions that used to take an - `evar_map ref` have been now switched to functions that will work in +- `Constrinterp.*`: generally, many functions that used to take an + `evar_map ref` have now been switched to functions that will work in a functional way. The old style of passing `evar_map`s as references is not supported anymore. @@ -260,16 +286,16 @@ We have changed the representation of the following types: Some tactics and related functions now support static configurability, e.g.: -- injectable, dEq, etc. takes an argument ~keep_proofs which, - - if None, tells to behave as told with the flag Keep Proof Equalities - - if Some b, tells to keep proof equalities iff b is true +- `injectable`, `dEq`, etc. take an argument `~keep_proofs` which, + - if `None`, tells to behave as told with the flag `Keep Proof Equalities` + - if `Some b`, tells to keep proof equalities iff `b` is true Declaration of printers for arguments used only in vernac command -- It should now use "declare_extra_vernac_genarg_pprule" rather than - "declare_extra_genarg_pprule", otherwise, a failure at runtime might +- It should now use `declare_extra_vernac_genarg_pprule` rather than + `declare_extra_genarg_pprule`, otherwise, a failure at runtime might happen. An alternative is to register the corresponding argument as - a value, using "Geninterp.register_val0 wit None". + a value, using `Geninterp.register_val0 wit None`. Types Alias deprecation and type relocation. @@ -312,7 +338,7 @@ functions when some given constants are traversed: * `declare_reduction_effect`: to declare a hook to be applied when some constant are visited during the execution of some reduction functions - (primarily cbv). + (primarily `cbv`). * `set_reduction_effect`: to declare a constant on which a given effect hook should be called. diff --git a/dev/doc/profiling.txt b/dev/doc/profiling.txt index 45766293c7..29e87df6b8 100644 --- a/dev/doc/profiling.txt +++ b/dev/doc/profiling.txt @@ -7,7 +7,7 @@ want to profile time or memory consumption. AFAIK, this only works for Linux. In Coq source folder: -opam switch 4.02.3+fp +opam switch 4.05.0+trunk+fp ./configure -local -debug make perf record -g bin/coqtop -compile file.v diff --git a/dev/doc/release-process.md b/dev/doc/release-process.md index 1821a181f1..b33a1cbd73 100644 --- a/dev/doc/release-process.md +++ b/dev/doc/release-process.md @@ -6,6 +6,35 @@ the present checklist. - [ ] Change the version name to the next major version and the magic numbers (see [#7008](https://github.com/coq/coq/pull/7008/files)). +- [ ] Update the compatibility infrastructure, which consists of doing + the following steps. Note that all but the final step can be + performed automatically by + [`dev/tools/update-compat.py`](/dev/tools/update-compat.py) so + long as you have already updated `coq_version` in + [`configure.ml`](/configure.ml). + + [ ] Add a file `theories/Compat/CoqXX.v` which contains just the header + from [`dev/header.ml`](/dev/header.ml) + + [ ] Add the line `Require Export Coq.Compat.CoqXX.` at the top of + `theories/Compat/CoqYY.v`, where Y.Y is the version prior to X.X. + + [ ] Delete the file `theories/Compat/CoqWW.v`, where W.W is three versions + prior to X.X. + + [ ] Update + [`doc/stdlib/index-list.html.template`](/doc/stdlib/index-list.html.template) + with the deleted/added files. + + [ ] Remove any notations in the standard library which have `compat "W.W"`. + + [ ] Update the type `compat_version` in [`lib/flags.ml`](/lib/flags.ml) by + bumping all the version numbers by one, and update the interpretations + of those flags in [`toplevel/coqargs.ml`](/toplevel/coqargs.ml) and + [`vernac/g_vernac.mlg`](/vernac/g_vernac.mlg). + + [ ] Update the files + [`test-suite/success/CompatCurrentFlag.v`](/test-suite/success/CompatCurrentFlag.v), + [`test-suite/success/CompatPreviousFlag.v`](/test-suite/success/CompatPreviousFlag.v), + and + [`test-suite/success/CompatOldFlag.v`](/test-suite/success/CompatOldFlag.v) + by bumping all version numbers by 1. + + [ ] Decide what to do about all test-suite files which mention `-compat + W.W` or `Coq.Comapt.CoqWW` (which is no longer valid, since we only + keep compatibility against the two previous versions) - [ ] Put the corresponding alpha tag using `git tag -s`. The `VX.X+alpha` tag marks the first commit to be in `master` and not in the branch of the previous version. @@ -57,7 +86,6 @@ ## Before the beta release date ## - [ ] Ensure the Credits chapter has been updated. -- [ ] Ensure an empty `CompatXX.v` file has been created. - [ ] Ensure that an appropriate version of the plugins we will distribute with Coq has been tagged. - [ ] Have some people test the recently auto-generated Windows and MacOS |