mirror of
https://github.com/Mercury-Language/mercury.git
synced 2026-04-23 05:13:48 +00:00
0beac98b61
compiler/notes/c_coding_standard.html:
Describe module header comments just once, not twice.
Expand on what may be in such comments.
Fix some oversights. For example, until now we didn't say that
a developer needs git (!), and we didn't say where the definitions,
as opposed to declarations, of any global variables exported from
a module should go.)
Improve the wording of several explanations.
Make some lists of things into item lists.
Expand tabs.
compiler/notes/glossary.html:
Describe what HLDS, LLDS and MLDS mean in more detail.
compiler/notes/overall_design.html:
Delete the reference to the long-deleted analysis directory.
compiler/notes/allocation.html:
compiler/notes/reviews.html:
compiler/notes/upgrade_boehm_gc.html:
Fix indentation.
346 lines
8.3 KiB
HTML
346 lines
8.3 KiB
HTML
<!--
|
|
vim: ts=4 sw=4 expandtab ft=html
|
|
-->
|
|
|
|
<html>
|
|
<head>
|
|
<title>
|
|
How to upgrade to a new version of Boehm Garbage Collector in Mercury.
|
|
</title>
|
|
</head>
|
|
|
|
<body>
|
|
|
|
<h1>How to upgrade to a new version of Boehm Garbage Collector in Mercury.</h1>
|
|
|
|
<p>
|
|
<b>WARNING:</b>
|
|
This process is difficult and should not be undertaken lightly.
|
|
Before attempting to upgrade Boehm GC,
|
|
you should definitely discuss it on the reviews mailing list first.
|
|
</P>
|
|
|
|
<h2>The setup</h2>
|
|
|
|
<p>
|
|
This is the first attempt to update Boehm
|
|
since Mercury switched from CVS to Git.
|
|
Therefore, I have taken the opportunity to setup this process in a more
|
|
git-ish way (Boehm GC also uses git).
|
|
I set this up for version 7.4.2 of the collector and libatomic_ops.
|
|
</p>
|
|
|
|
<p>
|
|
Over time we have made some changes to the collector,
|
|
some of which have not been pushed upstream.
|
|
The changes that have not been pushed upstream must be managed by us.
|
|
I've forked the bdwgc and libatomic_opts repositories.
|
|
Our forks are currently located here:
|
|
</p>
|
|
|
|
<table>
|
|
<tr><th></th><th>Web</th><th>git</th><th>branch</th></tr>
|
|
<tr>
|
|
<td>
|
|
BDW GC
|
|
</td>
|
|
<td>
|
|
<a href="https://github.com/Mercury-Language/bdwgc">
|
|
https://github.com/Mercury-Language/bdwgc
|
|
</a>
|
|
</td>
|
|
<td>
|
|
<code>https://github.com/Mercury-Language/bdwgc.git</code>
|
|
</td>
|
|
<td>
|
|
release-7_4-mercury
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
libatomic_ops
|
|
</td>
|
|
<td>
|
|
<a href="https://github.com/Mercury-Language/libatomic_ops">
|
|
https://github.com/Mercury-Language/libatomic_ops
|
|
</a>
|
|
</td>
|
|
<td>
|
|
<code>https://github.com/Mercury-Language/libatomic_ops.git</code>
|
|
</td>
|
|
<td>
|
|
release-7_4-mercury
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>
|
|
On a clean checkout of the Mercury repository,
|
|
I created a branch off of the master branch.
|
|
</p>
|
|
|
|
<code><pre>
|
|
$ git branch upgrade_boehm master
|
|
$ git checkout upgrade_boehm
|
|
</pre></code>
|
|
|
|
<p>
|
|
Then, on this branch I deleted the existing boehm_gc directory from the
|
|
repository.
|
|
</p>
|
|
|
|
<code><pre>
|
|
$ rm -rf boehm_gc
|
|
$ git commit -a
|
|
</pre></code>
|
|
|
|
<p>
|
|
Next we add the bdwgc and libatomic_ops repositories as git submodules.
|
|
This basically creates a reference from the Mercury repository to these
|
|
other repositories without importing their history into the Mercury
|
|
repository.
|
|
</p>
|
|
<p>
|
|
The references to submodules are relative. So if the remote named origin
|
|
has the url
|
|
<code>https://www.github.com/Mercury-Language/mercury.git</code>
|
|
then we can have git look for the bdwgc repository at the relative path
|
|
<code>../bdwgc.git</code> or
|
|
<code>https://www.github.com/Mercury-Language/bdwgc.git</code>.
|
|
</p>
|
|
|
|
<code><pre>
|
|
$ git submodule add -b release-7_4-mercury ../bdwgc.git boehm_gc
|
|
$ git submodule add -b release-7_4-mercury ../libatomic_ops.git libatomic_ops
|
|
</pre></code>
|
|
|
|
<p>
|
|
I've written a script named <code>prepare.sh</code> and committed it, it can
|
|
be used to initialize and checkout the submodules.
|
|
</p>
|
|
|
|
<h2>Mercury's customisations to the Boehm GC</h2>
|
|
|
|
<p>
|
|
I've created a branch named <code>mercury7_2</code>
|
|
based on the <code>gc7_2</code> tag in the bdwgc repository.
|
|
This branch contains the Mercury customisations to boehm_gc as a series of
|
|
patches.
|
|
Then to upgrade to 7.4.2 I created a new branch <code>release-7_4-mercury</code>
|
|
(from <code>mercury7_2</code>),
|
|
switched to it, and rebased it onto the point in the boehm_gc tree that
|
|
represents the BDWGC 7.4.2 release, that is the tag <code>gc7_4_2</code>:
|
|
</p>
|
|
|
|
<code><pre>
|
|
$ git branch release-7_4-mercury mercury7_2
|
|
$ git checkout release-7_4-mercury
|
|
$ git rebase --onto gc7_4_2 gc7_2
|
|
</pre></code>
|
|
|
|
<p>
|
|
I needed to solve several merge conflicts to complete the rebase.
|
|
</p>
|
|
|
|
<h2>Pulling changes from upstream</h2>
|
|
|
|
<p>
|
|
The final step is how to update Mercury's copy of the collector when there
|
|
are changes upstream.
|
|
At the time of writing there are some important patches on the collector's
|
|
<code>release-7_4</code> branch (The TSX bug).
|
|
</p>
|
|
|
|
<code><pre>
|
|
$ git remote -v
|
|
github-ivan https://github.com/ivmai/bdwgc.git (fetch)
|
|
github-ivan https://github.com/ivmai/bdwgc.git (push)
|
|
github-mercury https://github.com/Mercury-Language/bdwgc.git (fetch)
|
|
github-mercury git@github.com:Mercury-Language/bdwgc.git (push)
|
|
origin ../bdwgc.git (fetch)
|
|
origin ../bdwgc.git (push)
|
|
</pre></code>
|
|
|
|
<p>
|
|
Starting with libatomic_ops I update the <code>release-7_4</code> branch to
|
|
the latest changes and then rebase Mercury's customisations (in the
|
|
<code>release-7_4-mercury</code> branch) on top of those.
|
|
</p>
|
|
|
|
<code><pre>
|
|
$ git checkout release-7_4
|
|
$ git pull github-ivan release-7_4
|
|
$ git push github-mercury release-7_4 # Optional
|
|
$ git checkout release-7_4-mercury
|
|
$ git pull github-mercury release-7_4-mercury
|
|
$ git rebase release-7_4
|
|
</pre></code>
|
|
|
|
<p>
|
|
There are only two Mercury-specific change so this went smoothly.
|
|
However, the second change commits some autogenerated files, this makes it
|
|
easier to build libatomic_ops inside the Mercury tree.
|
|
We need to regenerate those files.
|
|
</p>
|
|
|
|
<code><pre>
|
|
$ ./autogen.sh
|
|
$ git commit --amend -a
|
|
</pre></code>
|
|
|
|
<p>
|
|
Double check that you got everything:
|
|
</p>
|
|
|
|
<code><pre>
|
|
$ git status --ignored
|
|
</pre></code>
|
|
|
|
<p>
|
|
Now, publish this change with <code>--force</code> because we are changing
|
|
history.
|
|
</p>
|
|
|
|
<code><Pre>
|
|
$ git tag release-7_4-mercury-20160915
|
|
$ git push --force github-mercury release-7_4-mercury
|
|
$ git push github-mercury --tags
|
|
</pre></code>
|
|
|
|
<p>
|
|
Now do the same for boehm_gc,
|
|
however I've documented two examples depending on what you're trying to
|
|
achieve.
|
|
</p>
|
|
|
|
<ol>
|
|
<li>
|
|
<p>
|
|
Upgrade to a newer patch within the 7.4 release.
|
|
</p>
|
|
|
|
<code><pre>
|
|
$ git checkout release-7_4
|
|
$ git pull github-ivan release-7_4
|
|
$ git push github-mercury release-7_4 # Optional
|
|
$ git checkout release-7_4-mercury
|
|
$ git pull github-mercury release-7_4-mercury
|
|
$ git rebase release-7_4
|
|
</pre></code>
|
|
|
|
<p>
|
|
This rebase hard two merge conflicts however they were simple.
|
|
</p>
|
|
|
|
</li>
|
|
<li>
|
|
<p>
|
|
Upgrade from the 7.4 release to the 7.6 release
|
|
</p>
|
|
|
|
<code><pre>
|
|
$ git checkout -b release-7_6 github-ivan/release-7.6
|
|
$ git push github-mercury release-7_6 # Optional
|
|
$ git checkout -b release-7_6-mercury release-7_4-mercury
|
|
$ git rebase release-7_6
|
|
</pre></code>
|
|
|
|
<p>
|
|
There were a number of conflicts and some patches have since been merged
|
|
upstream so I was able to drop them entirely.
|
|
</p>
|
|
</li>
|
|
</ol>
|
|
|
|
<p>
|
|
Now I need to update the version of libatomic_ops we include with as a
|
|
submodule in the boehm repository.
|
|
If the branch name in libatomic_ops was changing I would need to check
|
|
the .gitmodules file, but in this example it isn't.
|
|
</p>
|
|
|
|
<code><pre>
|
|
$ git submodule update --remote --checkout
|
|
$ git add libatomic_ops
|
|
$ git commit
|
|
</pre></code>
|
|
|
|
<p>
|
|
Depending on which step we chose above,
|
|
tag and push these changes.
|
|
</p>
|
|
|
|
<ol>
|
|
<li>
|
|
<code><pre>
|
|
$ git tag release-7_4-mercury-YYYYMMDD
|
|
$ git push --force github-mercury release-7_4-mercury
|
|
$ git push github-mercury --tags
|
|
</pre></code>
|
|
</li>
|
|
<li>
|
|
<code><pre>
|
|
$ git tag release-7_6-mercury-20160916
|
|
$ git push github-mercury release-7_6-mercury
|
|
$ git push github-mercury --tags
|
|
</pre></code>
|
|
</li>
|
|
</ol>
|
|
|
|
<p>
|
|
Back in the mercury repository I needed to point the boehm_gc submodule to a
|
|
different branch,
|
|
Depending on which option we chose above we may need to update the branch
|
|
name that the Mercury repository refers to.
|
|
</p>
|
|
|
|
<ol>
|
|
<li>
|
|
<p>The branch name hasn't changed</p>
|
|
</li>
|
|
<li>
|
|
<p>
|
|
The branch name was <code>release-7_4_mercury</code> and is now
|
|
<code>release-7_6-mercury</code>.
|
|
The branch is adjusted by editing .gitmodules
|
|
</p>
|
|
|
|
<code><pre>
|
|
$ vim .gitmodules
|
|
</pre></code>
|
|
</li>
|
|
</ol>
|
|
|
|
<p>
|
|
In any case you will need to tell git that the branches have been updated,
|
|
and these submodules should now refer to different <i>git IDs</i>.
|
|
</p>
|
|
|
|
<code><pre>
|
|
$ git submodule update --remote --checkout
|
|
$ git add .gitmodules boehm_gc
|
|
$ git commit
|
|
</pre></code>
|
|
|
|
<p>
|
|
Once done,
|
|
bootcheck the compiler in at least asm_fast.gc and hlc.gc.
|
|
Then use the new system to do an install (with non-empty LIBGRADES)
|
|
and test that the installed version can compile some test programs.
|
|
This is because the update may have added some new files which may not be
|
|
copied into the install directories.
|
|
Some build scripts may also need to be updated (in particular
|
|
tools/bootcheck and scripts/prepare_install_dir.in).
|
|
</p>
|
|
|
|
<p>
|
|
Finally update .README.in (in the root directory) and
|
|
bindist/bindist.README to reflect the current version of the collector
|
|
being used.
|
|
Then commit these changes and have the changes reviewed before pushing them
|
|
into the public repository.
|
|
</p>
|
|
|
|
</body>
|
|
</html>
|