https://gambitscheme.org/wiki/api.php?action=feedcontributions&user=S450r1&feedformat=atomGambit wiki - User contributions [en]2024-03-28T13:02:29ZUser contributionsMediaWiki 1.35.3https://gambitscheme.org/wiki/index.php?title=Contributing_Patches_to_Gambit_Source_Code&diff=2366Contributing Patches to Gambit Source Code2010-03-29T21:33:28Z<p>S450r1: Add information from http://article.gmane.org/gmane.lisp.scheme.gambit/4399</p>
<hr />
<div>__NOTOC__ __NOEDITSECTION__<br />
The Gambit [[Source code repository | source code repository]] is<br />
managed with the [http://git.or.cz/ git]<br />
distributed version control system.<br />
<br />
Each developer uses a local copy of the central repository. The<br />
copies can be edited independently using any tool (editors, utility<br />
programs, etc). When a developer completes making a set of related<br />
changes they are recorded as a ''commit''. The developer can submit<br />
these changes to the Gambit maintainers as a ''patch''. If the patch is accepted<br />
then it will be applied to the repository by the Gambit maintainers<br />
and will become part of the central repository.<br />
<br />
This page only gives the main procedures and git commands that are needed<br />
to manage the local copy of the central repository.<br />
Please read the [http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html git tutorial] for<br />
typical usage instructions.<br />
<br />
==== Installing git ====<br />
<br />
Git was created for the development of the Linux kernel, and<br />
is sometimes preinstalled on Linux distributions.<br />
Prebuilt distributions of git and a source code distribution are<br />
available [http://git.or.cz/#download here].<br />
Please follow the installation instructions on the<br />
[http://git.or.cz/ git web site].<br />
<br />
To simplify usage of git the git configuration file '''$HOME/.gitconfig'''<br />
should be created and contain at least your username. There are<br />
many settings that can be specified<br />
such as the editor to use for entering the comment attached<br />
to a commit. For example, to use emacs:<br />
<br />
<pre><br />
[user]<br />
name = Marc Feeley<br />
email = feeley@iro.umontreal.ca<br />
[core]<br />
editor = emacs -nw<br />
[color]<br />
ui = auto<br />
</pre><br />
<br />
==== Obtaining a local copy of the Gambit source code ====<br />
<br />
The best way to obtain a local copy of the Gambit source code is to<br />
download and unpack a recent source code release. You need<br />
the '''developer''' version, which has a '''-devel''' in the tarball name.<br />
Normally the most recent source code release should be downloaded<br />
and you need at least v4.3.2 (the first version to support git).<br />
After that you can use the '''make update''' command to<br />
update your local copy with all the changes committed to<br />
the central source code repository.<br />
<br />
Get the most recent tarball from the <br />
[http://dynamo.iro.umontreal.ca/~gambit/wiki/index.php/Main_Page main Gambit page].<br />
<br />
<pre><br />
wget http://www.iro.umontreal.ca/~gambit/download/gambit/v4.3/source/gambc-v4_3_2-devel.tgz<br />
tar zxf gambc-v4_3_2-devel.tgz<br />
mv gambc-v4_3_2-devel gambit<br />
</pre><br />
<br />
Note that in anticipation of making changes to the source code the<br />
directory has been renamed to '''gambit''' to avoid thinking it is a<br />
pristine copy of a particular release.<br />
<br />
The system should then be prepared for modifications of the Scheme<br />
source code by creating a compiler for bootstrapping:<br />
<br />
<pre><br />
cd gambit<br />
./configure --enable-single-host<br />
make bootstrap<br />
</pre><br />
<br />
This will create the '''gsc-comp''' compiler, which is executed when a<br />
Scheme source code file in the Gambit system must be compiled<br />
following a change.<br />
<br />
==== Synchronizing with the central source code repository ====<br />
<br />
The local source code files can then be updated to contain the latest commits<br />
on the central source code repository with the command:<br />
<br />
<pre><br />
make update<br />
</pre><br />
<br />
This will call the '''git fetch''' and '''git checkout''' commands in a loop, so that the Gambit compiler<br />
for each release between the local copy's release and the most recent release are<br />
built in succession. This is necessary because the Gambit system is bootstrapped<br />
with itself, and to compile the runtime system for a specific version the Gambit<br />
compiler for that version must be used. If for some reason you need to do this<br />
manually the following procedure should be used. Assuming the local copy is currently<br />
at release v1.2.3 and that v1.2.5 is the most recent release, do this:<br />
<br />
<pre><br />
git checkout v1.2.4-bootstrap<br />
make bootstrap<br />
git checkout v1.2.4<br />
make bootclean bootstrap<br />
git checkout v1.2.5-bootstrap<br />
make bootstrap<br />
git checkout v1.2.5<br />
make bootclean bootstrap<br />
git checkout master<br />
make bootstrap<br />
</pre><br />
<br />
Note that the latest source code may be unstable. It is wise to check<br />
that it passes basic consistency checks by running the command '''make check'''.<br />
<br />
The local source code files can be updated to a specific version<br />
with the '''git checkout''' command.<br />
<br />
<pre><br />
git checkout v4.2.1<br />
</pre><br />
<br />
After this command it is not possible to build Gambit with<br />
a '''make''' because the local '''gsc-comp''' is not the appropriate<br />
version to compile the runtime system. One way around this problem<br />
is to download the release for that version in a different directory, do a<br />
'''make bootstrap''' in that directory, and then copy '''gsc-comp'''<br />
back here.<br />
<br />
==== Creating a commit ====<br />
<br />
A source code change may simply be modifications of existing<br />
files, deletions, and addition of new files.<br />
If a new file has been created git should be informed by entering:<br />
<br />
<pre><br />
git add newfile<br />
</pre><br />
<br />
After making a set of related changes it is customary to review which files have changed<br />
by executing the command:<br />
<br />
<pre><br />
make status<br />
</pre><br />
<br />
If all checks out, a commit is created with the command:<br />
<br />
<pre><br />
make commit<br />
</pre><br />
<br />
This command will pop up an editor to compose a comment describing the nature of the patch.<br />
Please use a short but descriptive comment on the first line of text entered.<br />
<br />
To get a list of the commits (starting with the latest, i.e. the '''HEAD''') use:<br />
<br />
<pre><br />
make log<br />
</pre><br />
<br />
==== Contributing a patch ====<br />
<br />
A patch file can be created using the '''git diff''' command. To include only the<br />
most recent commit use:<br />
<br />
<pre><br />
git diff HEAD~1 > my-patch<br />
</pre><br />
<br />
A range of patches can be specified like this:<br />
<br />
<pre><br />
git diff HEAD~7..HEAD~3 > my-patch<br />
</pre><br />
<br />
The patch file can then be submitted to the Gambit maintainers<br />
by sending the file by email to '''gambit@iro.umontreal.ca'''. For example:<br />
<br />
<pre><br />
mail -s "[PATCH] ,b command fix" gambit@iro.umontreal.ca < my-patch<br />
</pre><br />
<br />
==== Releasing a new version of Gambit ====<br />
<br />
This section contains some notes for the Gambit maintainers. It explains the steps to follow to release a new version of Gambit. '''The steps must be followed carefully or you may end up with a wedged system!'''<br />
<br />
===== Manual procedure =====<br />
<br />
Assume the latest release of Gambit is v1.2.3 and the new release will be v4.5.6.<br />
Because Gambit is bootstrapped with itself, releasing a new version of Gambit is a two step process.<br />
The Gambit compiler must first be modified so that it generates C code which references the '''gambit.h''' file version v4.5.6.<br />
Then the '''gambit.h''' file, '''configure.ac''' file, and other files with an embedded version number must be updated so they refer to version v4.5.6.<br />
<br />
'''1. Creating a Gambit compiler for version v4.5.6'''<br />
<br />
Make sure you have a working bootstrap compiler ('''gsc-comp''') and save a copy just in case:<br />
<br />
<pre><br />
make check<br />
make bootstrap<br />
cp gsc-comp gsc-comp.old<br />
</pre><br />
<br />
Now modify the definition of '''compiler-version''' in the file '''gsc/_parms.scm''' so that it refers to v4.5.6 (using a single integer encoding of the version number):<br />
<br />
<pre><br />
(define (compiler-version) 405006) ;; 100000*major + 1000*minor + revision<br />
</pre><br />
<br />
Now create the new bootstrap compiler and commit the change with an easily identifiable comment:<br />
<br />
<pre><br />
make bootstrap<br />
git commit -a -m "[COMPILER CHANGES NEEDED FOR v4.5.6] Changed version in compiler"<br />
git tag v4.5.6-bootstrap<br />
</pre><br />
<br />
Note that at this very point the new compiler will not pass the tests because the runtime still expects the old version number.<br />
<br />
'''2. Upgrading the runtime files from version v1.2.3 to v4.5.6'''<br />
<br />
For the C files generated from Scheme files the version numbers can easily be upgraded by compiling them from scratch using the new Gambit compiler.<br />
This will be done automatically by a '''make''' after a '''make bootclean'''. The other changes to the files are made by running the script '''misc/changev''' (this must be done first because it changes the file '''configure.ac''' which produces the '''configure''' script which must be run again).<br />
<br />
<pre><br />
misc/changev 102003 405006<br />
make bootclean<br />
./configure<br />
make<br />
make check # will fail test5 because version numbers have changed<br />
mv tests/mix.c tests/test5.ok<br />
make check # this time all tests should pass<br />
git commit -a -m "[RUNTIME CHANGES NEEDED FOR v4.5.6] Changed version of runtime using misc/changev"<br />
git tag v4.5.6<br />
</pre><br />
<br />
'''3. Creating prebuilt installers for version v4.5.6'''<br />
<br />
To create prebuilt installers for Mac OS and Windows you need a Mac with Xcode and Parallels workstation with Windows and the MinGW and Microsoft Visual C Express environments. The following command will build all variants of the installers (it takes about 2 hours in total):<br />
<br />
<pre><br />
make release<br />
</pre><br />
<br />
If no errors were reported then you can upload the new release to the Gambit repository using:<br />
<br />
<pre><br />
make publish-release<br />
</pre><br />
<br />
This will automatically send an announcement on the Gambit mailing list. You must manually update the main page of the Gambit Wiki so that it refers to the latest version.<br />
<br />
===== Automated procedure =====<br />
<br />
Step 1 and 2 in the above instructions are executed with the '''change-version''' make target:<br />
<br />
<pre><br />
make NEW_VERSION=v4.5.6 change-version<br />
</pre><br />
<br />
Alternatively, the '''new-revision''', '''new-minor''', or '''new-major''' make targets can be used<br />
to compute the new version number from the current version by incrementing one<br />
of the version number fields:<br />
<br />
<pre><br />
make new-revision<br />
</pre><br />
<br />
==== Troubleshooting ====<br />
<br />
A user was having trouble using trouble building an up-to-date version of Gambit starting from v4.3.2. '''make update''' was failing. Marc Feeley responded with an explanation and a solution.<br />
<br />
The solution is to download the latest version of Gambit and use that to run the '''make update''' in the git repository.<br />
<br />
Here's the [http://article.gmane.org/gmane.lisp.scheme.gambit/4399 reply]:<br />
<br />
<blockquote><br />
Let me explain the problem. If you're only interested in a solution: get v4.6.0 and a make update from that.<br />
</blockquote><br />
<br />
<blockquote><br />
Gambit is a self-hosting compiler. That means that it is bootstrapped using itself. Most of the system is<br />
implemented in Scheme (not just the libraries, but the compiler itself). So when a change is made in the<br />
compiler's source code, it must be compiled with the current version of the compiler. Roughly speaking,<br />
version 2 must be compiled with version 1. Then when changes are made (to get the source code of version 3),<br />
then version 3 must be compiled with version 2. And so on. When you "make update" the build process executes<br />
the chain of self compilations that led to the most recent version of Gambit. In other words, if the most<br />
recent Gambit is v4 and you currently have v1 installed, then the "make update" will: compile the v2 source<br />
with the v1 executable to get the v2 executable, then it will compile the v3 source with the v2 executable to<br />
get the v3 executable, and finally compile the v4 source with the v3 executable to get the v4 executable. <br />
This chain must be followed because features that are used in the source code of the most recent version of<br />
the compiler may have appeared (i.e. were implemented) in an intermediate version of the compiler.<br />
</blockquote><br />
<br />
<blockquote><br />
This self dependency is not easy to handle in the build process and makefiles, and currently there is a bug. <br />
In your particular case, Gambit v4.3.2 does not support the same command line options as more recent<br />
version of Gambit. So somewhere in this chain of commits, the makefiles were not consistent with the then<br />
current compiler. But because the commits can't be "taken back" the self compilation sequence that "make<br />
update" executes has some version transitions that will forever be broken. I haven't looked into ways<br />
(automatic tool, or better version changing habits) to avoid this problem in the future.<br />
</blockquote><br />
<br />
[[Category: Development]]</div>S450r1