From ae80c890e972a12535f6de20b970616bfa4b3585 Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Fri, 12 Feb 2021 07:45:51 -0700 Subject: [PATCH] update source READMEs on modifying versions and pb bootfiles --- racket/src/README.txt | 21 +++++++++++++++++++++ racket/src/bc/README.txt | 10 +++++----- racket/src/cs/README.txt | 38 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 64 insertions(+), 5 deletions(-) diff --git a/racket/src/README.txt b/racket/src/README.txt index befd9adaac..d476418ce2 100644 --- a/racket/src/README.txt +++ b/racket/src/README.txt @@ -451,6 +451,27 @@ When building BC for iOS, you may need to add `--disable-cify` for inheriting the build machine's disposition. +======================================================================== + Modifying Racket +======================================================================== + +See "cs/README.txt" and "bc/README.txt" for information about +modifying those implementations of Racket, but one thing they have in +common is updating the Racket version number. The source for the +Racket version number is shared in "version/racket_version.h". + +The version number for the "base" package needs to be updated +separately. If this directory is part of a clone of the Git repository +for Racket, then the "base" version is in "../../pkgs/base/info.rkt". + +Unfortunately, there's no single source for the version number in both +Racket and "base". Those are extracted as subtrees into separate +distributions, and the point of a version in each place is to detect a +mismatch between those extracted distributions. The "version.rktl" +test in Racket's core test suite effectively checks that they're in +sync within the Racket repo. + + ======================================================================== Test Suite ======================================================================== diff --git a/racket/src/bc/README.txt b/racket/src/bc/README.txt index f94f2dacab..cb05a3e16f 100644 --- a/racket/src/bc/README.txt +++ b/racket/src/bc/README.txt @@ -96,11 +96,11 @@ information. Modifying Racket ======================================================================== -If you modify Racket and change any primitive syntax or the collection -of built-in identifiers, be sure to update the version number in -"../version/racket_version.h", so that various tools know to rebuild -bytecode. If you add or remove primitives, you'll also need to adjust -the counter in "src/schminc.h" . +If you modify Racket in a way that changes compiled code, including +changing the set of primitives, be sure to update the version number +in "../version/racket_version.h", so that various tools know to +rebuild bytecode. If you add or remove primitives, you'll also need to +adjust the counter in "src/schminc.h" . Some general guidelines for modying this code: diff --git a/racket/src/cs/README.txt b/racket/src/cs/README.txt index 10e03be60d..95d63e090f 100644 --- a/racket/src/cs/README.txt +++ b/racket/src/cs/README.txt @@ -536,3 +536,41 @@ conversion of a primitive reference to unsafe or not based on meant to expand to uses of unsafe operations should refer to the operations using `#3%`; beware that such a reference will stay unsafe, even if `UNSAFE_COMP` is disabled in the makefile. + + +======================================================================== + Modifying Racket +======================================================================== + +If you modify Racket in a way that changes compiled code, including +changing the set of primitives, be sure to update the version number +in "../version/racket_version.h", so that various tools know to +rebuild bytecode. + +If you modify the Chez Scheme implementation in "../ChezScheme" in a +way that changes compiled code, then you should also update the Chez +Scheme version number in "../ChezScheme/s/cmacro.ss" and in +"../ChezScheme/makefiles/Mf-install". For more about Chez Scheme's +implementation and bootstrap, see "../ChezScheme/IMPLEMENTATION.md". + +If you're working in a checkout of the Racket Git repo, then when you +update Chez Scheme in a way that needs new pb bootfiles, the updated +bootfiles should be pushed to a new branch of the Racket pb repo and +the Racket repo's top-level makefile should be updated to refer to the +branch. Assuming that a working `racket` is in your path: + + * Update ".makefile" in the checkout root to set `PB_BRANCH` to a + fresh branch name, typically based on the Racket version number. + + * Use `make makemake` in the checkout root to build "Makefile" from + ".makefile" using `racket`. + + * Use `make pb-build` in the checkout root to build pb bootfiles + using `racket`. + + * Use `make pb-stage` in the checkout root to set up the new branch + locally. You could check that "../ChezScheme/boot/pb" looks + sensible at this point. The local branch checkout should have a + single commit in its history. + + * Use `make pb-push` to push the new branch to the Racket pb repo.