Skip to content

Commit

Permalink
Merge pull request #1205 from checkedc/update-docs
Browse files Browse the repository at this point in the history
Fix up URLs in Checked C docs.
  • Loading branch information
dtarditi authored Sep 2, 2024
2 parents 74ec828 + 05942cc commit 33c5d72
Show file tree
Hide file tree
Showing 5 changed files with 64 additions and 64 deletions.
2 changes: 1 addition & 1 deletion clang/docs/checkedc/3C/CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Contributing to 3C

Issues and pull requests related to 3C should be submitted to
[checkedc](https://github.com/checkedc/checkedc-llvm-project) repo.
[checkedc](https://github.com/checkedc/checkedc-clang) repo.

## Issues

Expand Down
6 changes: 3 additions & 3 deletions clang/docs/checkedc/3C/INSTALL.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,15 +19,15 @@ fiddly](#mac-os-x), but we have managed it so far.

## Basics

Start by cloning [checkedc](https://github.com/checkedc/checkedc-llvm-project) repo (or, of course, a
Start by cloning [checkedc](https://github.com/checkedc/checkedc-clang) repo (or, of course, a
third-party fork, though we can't be responsible for that). Assuming
you have already cloned one of these repositories, run the following
(from the `checkedc-llvm-project` directory or whatever you named your clone)
(from the `checkedc-clang` directory or whatever you named your clone)
for a basic build:

```
# Get a copy of the Checked C system headers. Use Microsoft's
# "checkedc" repository regardless of which "checkedc-llvm-project"
# "checkedc" repository regardless of which "checkedc-clang"
# repository you use.
git clone https://github.com/microsoft/checkedc llvm/projects/checkedc-wrapper/checkedc
Expand Down
12 changes: 6 additions & 6 deletions clang/docs/checkedc/3C/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,15 +26,15 @@ found [here](https://3clsp.github.io/).
## What 3C users should know about the development process

The development of Checked C exclusively takes place in the repository
located at https://github.com/checkedc/checkedc-llvm-project. 3C is included
located at https://github.com/checkedc/checkedc-clang. 3C is included
in the Checked C codebase. Initially 3C development was led by [Correct
Computation, Inc.](https://correctcomputation.com/). As of now, 3C is
integrated into [checkedc](https://github.com/checkedc/checkedc-llvm-project)
checkedc-llvm-project repo and all furthur development will be in
[checked](https://github.com/checkedc/checkedc-llvm-project) repo.
integrated into [checkedc](https://github.com/checkedc/checkedc-clang)
checkedc-clang repo and all furthur development will be in
[checked](https://github.com/checkedc/checkedc-clang) repo.

Issues and pull requests related to 3C should be submitted to
[checkedc](https://github.com/checkedc/checkedc-llvm-project)
[checkedc](https://github.com/checkedc/checkedc-clang)
repository; see [CONTRIBUTING.md](CONTRIBUTING.md) for more
information.

Expand All @@ -44,4 +44,4 @@ establish its public presence and processes.
As noted in the [setup instructions](INSTALL.md#basics), both 3C and
the Checked C compiler depend on the Checked C system headers, which
Microsoft maintains in [a subdirectory of a separate repository named
`checkedc`](https://github.com/microsoft/checkedc/tree/master/include).
`checkedc`](https://github.com/microsoft/checkedc/tree/main/include).
12 changes: 6 additions & 6 deletions clang/docs/checkedc/Setup-and-Build.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ See the file LICENSE.TXT in for complete details of licensing.

The LLVM/Clang repo has two branches:

- master: the main development branch for Checked C. All changes committed here
- main: the main development branch for Checked C. All changes committed here
have been code reviewed and passed testing.
- baseline: these are pristine copies of the Github mirrors. Do not commit
changes for Checked C to the baseline branches.
Expand All @@ -87,15 +87,15 @@ compiler. The Checked C repo tests are licensed under the
[MIT license](https://opensource.org/licenses/MIT). The
[Checked C LLVM Test Suite](http://github.com/checkedc/checkedc-llvm-test-suite)
is a fork of the
[LLVM test suite mirror](https://github.com/llvm-mirror/test-suite). The LLVM
[LLVM test suite mirror](https://github.com/llvm/llvm-test-suite). The LLVM
test suite is for extended testing and includes applications and benchmarks.
Some of these benchmarks have been modified to use Checked C extensions.

We do not recommend that developers install sources for it or the Checked C
version by default. The test suite is meant to be run as part of automated
integration testing or for changes that require extensive testing, not as part
of day-to-day development. For developers who need to install it, information is
[here](https://github.com/checkedc/checkedc-llvm-test-suite/blob/master/README.md).
[here](https://github.com/checkedc/checkedc-llvm-test-suite/blob/main/README.md).

## Checkout and Build Instructions for Checked C Compiler

Expand All @@ -116,7 +116,7 @@ directory as \<WORK_DIR\>.
2. Clone the `checkedc-clang` repository:

```
git clone https://github.com/checkedc/checkedc-llvm-project src
git clone https://github.com/checkedc/checkedc-clang src
```

3. The Checked C language header files and tests are stored in a folder within
Expand Down Expand Up @@ -203,7 +203,7 @@ directory as \<WORK_DIR\>. In your Visual Studio Command Prompt:
Unix/Linux directions. Otherwise, follow these directions:
```
git clone -c core.autocrlf=false https://github.com/checkedc/checkedc-llvm-project src
git clone -c core.autocrlf=false https://github.com/checkedc/checkedc-clang src
```
3. The Checked C language header files and tests are stored in a folder within `llvm\project`.
Expand Down Expand Up @@ -293,5 +293,5 @@ directory to the build directory, and run
Most developers can ignore this section. We periodically update the Checked C
source code to newer versions of the source code for LLVM/Clang. The directions
for the process of updating the baseline and master branches to newer versions
for the process of updating the baseline and main branches to newer versions
of LLVM/Clang are [here](Update-to-latest-LLVM-sources.md).
96 changes: 48 additions & 48 deletions clang/docs/checkedc/Update-to-latest-LLVM-sources.md
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
# Instructions for updating to the latest LLVM/Clang sources

We are staying in sync with the upstream LLVM/Clang repository. The `baseline`
branch of the `checkedc-llvm-project` repository is a pristine copy of LLVM/Clang
sources, and the `master` branch contains LLVM/Clang sources plus the support
branch of the `checkedc-clang` repository is a pristine copy of LLVM/Clang
sources, and the `main` branch contains LLVM/Clang sources plus the support
for Checked C language extensions. We periodically upgrade the `baseline` branch
and the `master` branch to the sources of the most recent releases from the
and the `main` branch to the sources of the most recent releases from the
upstream LLVM/Clang repository.

The branching and merging policies of the `checkedc-llvm-project` repository are
The branching and merging policies of the `checkedc-clang` repository are
aligned with the versioning and branching of upstream LLVM/Clang repository in
order to closely follow the LLVM/Clang releases. LLVM/Clang releases are
versioned as &lt;major-version&gt;.&lt;minor-version&gt;.&lt;patch-version&gt;.
Expand All @@ -19,13 +19,13 @@ is created. Bug fixes go on the release branch and only some of these bug fixes
get merged back into the `main` branch. Typically, LLVM/Clang makes two final
releases for each major version.

Now we describe our approach for upgrading the `checkedc-llvm-project` repository to
Now we describe our approach for upgrading the `checkedc-clang` repository to
LLVM/Clang sources corresponding to the two releases for each major version,
for example, 12.0.0 and 12.0.1. The upgrade is performed in two phases as
described below. This description is followed by detailed instructions for each
phase.

**Phase 1**: We upgrade the `master` branch of the `checkedc-llvm-project` repository
**Phase 1**: We upgrade the `main` branch of the `checkedc-clang` repository
up to the commit hash on the `main` branch of the LLVM/Clang repository at which
the branch `release/12.x` is created - we shall refer to this commit hash as
&lt;branch-point-of-12-on-main&gt;. We get this commit hash by executing the
Expand All @@ -34,23 +34,23 @@ repository. Note that &lt;branch-point-of-12-on-main&gt;
needs to be the full commit hash and not just the 7-digit abbreviation. This
phase constitutes the major portion of the developer effort towards the merge.

**Phase 2**: We create a branch called `release_12.x` off the `master` branch in
the `checkedc-llvm-project` repository. Then there are two sub-phases:
**Phase 2**: We create a branch called `release_12.x` off the `main` branch in
the `checkedc-clang` repository. Then there are two sub-phases:
- When we wish to make a Checked C compiler release based on the 12.0.0
release of LLVM/Clang:
- We first upgrade the `release_12.x` branch (of the `checkedc-llvm-project`
- We first upgrade the `release_12.x` branch (of the `checkedc-clang`
repository) to the sources corresponding to the 12.0.0 release on the
`release/12.x` branch of the LLVM/Clang repository.
- Next, we merge Checked C features and bug fixes from the `master` branch
- Next, we merge Checked C features and bug fixes from the `main` branch
to the `release_12.x` branch.
- The release of the Checked C compiler happens from the `release_12.x`
branch.
- When we wish to make a Checked C compiler release based on the 12.0.1
release of LLVM/Clang:
- We upgrade the same `release_12.x` branch (of the `checkedc-llvm-project`
- We upgrade the same `release_12.x` branch (of the `checkedc-clang`
repository) to the sources corresponding to the 12.0.1 release on the
`release/12.x` branch of the LLVM/Clang repository.
- Next, we merge Checked C features and bug fixes from the `master` branch
- Next, we merge Checked C features and bug fixes from the `main` branch
to the `release_12.x` branch.
- The release of the Checked C compiler happens from the `release_12.x`
branch.
Expand All @@ -62,11 +62,11 @@ repository will break Checked C build and tests.

Note that Phase 1 and the sub-phases of Phase 2 may not be executed one after
another in one continuous stretch. They may be spread over several weeks and may
be interspersed with Checked C development on the `master` branch.
be interspersed with Checked C development on the `main` branch.

## Detailed Instructions - Phase 1

1. Create a new branch off the `baseline` branch in the `checkedc-llvm-project`
1. Create a new branch off the `baseline` branch in the `checkedc-clang`
repository. Let us call this new branch `updated_baseline`.
```
git checkout -b updated_baseline baseline
Expand All @@ -87,20 +87,20 @@ branch `updated_baseline` to be a descendant of branch `baseline`.
git checkout baseline
git merge --ff-only updated_baseline
```
5. Create a new branch, say, `updated_baseline_master_12` from the `baseline`
5. Create a new branch, say, `updated_baseline_main_12` from the `baseline`
branch.
```
git checkout -b updated_baseline_master_12 baseline
git checkout -b updated_baseline_main_12 baseline
```
6. Merge the `master` branch of the checkedc-llvm-project repository into the
`updated_baseline_master_12` branch. This merge may cause several merge
6. Merge the `main` branch of the checkedc-clang repository into the
`updated_baseline_main_12` branch. This merge may cause several merge
conflicts and test case failures. After the merge command, git may suggest to
you to set `merge.renamelimit` to a specific value. It is a good idea to set it
as suggested and re-run the merge. The last section in this document gives
guidelines on fixing the merge conflicts and test failures.
```
git checkout updated_baseline_master_12
git merge master > merge_conflict_list.txt
git checkout updated_baseline_main_12
git merge main > merge_conflict_list.txt
```
7. The resolution of test failures may require you to cherry-pick commits from
the upstream LLVM/Clang repository. Record the cherry-picked commits in the
Expand All @@ -112,45 +112,45 @@ repository.
git cherry-pick -x <commit-to-cherry-pick>
```
8. While the merge conflicts and test failures are being fixed, it is possible
that the `master` branch has had several commits. Merge the `master` branch into
`updated_baseline_master_12` branch, and resolve the new conflicts and failures
that the `main` branch has had several commits. Merge the `main` branch into
`updated_baseline_main_12` branch, and resolve the new conflicts and failures
if necessary.
```
git merge master >> merge_conflict_list.txt
git merge main >> merge_conflict_list.txt
```
9. After all the merge conflicts and test failures on the local machine are
fixed, push the `baseline` and `updated_baseline_master_12` branches to the
fixed, push the `baseline` and `updated_baseline_main_12` branches to the
remote repository and execute the ADO tests on branch
`updated_baseline_master_12`. Commits to the `master` branch should be held off
`updated_baseline_main_12`. Commits to the `main` branch should be held off
during the final execution of these tests, i.e. just prior to executing step 10
below.
```
git push origin baseline
git push origin updated_baseline_master_12
git push origin updated_baseline_main_12
```
10. After the ADO tests are successful, merge the `updated_baseline_master_12`
branch into `master` and push to the remote repository. If all the changes on
the `master` branch have been merged into the `updated_baseline_master_12`
10. After the ADO tests are successful, merge the `updated_baseline_main_12`
branch into `main` and push to the remote repository. If all the changes on
the `main` branch have been merged into the `updated_baseline_main_12`
branch in step 8, then it should be possible to do a fast-forward merge of
branch `updated_baseline_master_12` into the `master` branch.
branch `updated_baseline_main_12` into the `main` branch.
```
git checkout master
git merge --ff-only updated_baseline_master_12
git push origin master
git checkout main
git merge --ff-only updated_baseline_main_12
git push origin main
```

## Detailed Instructions - Phase 2
We give the instructions for the first sub-phase of Phase 2. Similar steps
have to be followed for the other sub-phase.

1. Create a new branch, called `release_12.x`, from the `master` branch in the
`checkedc-llvm-project` repository. If the branch already exists, then merge the
`master` branch into it. Resolve merge conflicts and test failures if any.
1. Create a new branch, called `release_12.x`, from the `main` branch in the
`checkedc-clang` repository. If the branch already exists, then merge the
`main` branch into it. Resolve merge conflicts and test failures if any.
```
git checkout -b release_12.x master
git checkout -b release_12.x main
OR
git checkout release_12.x
git merge master
git merge main
```
2. Upgrade the branch `release_12.x` to the LLVM/Clang sources corresponding to
the 12.0.0 release. The commit hash associated with the 12.0.0 release is given
Expand Down Expand Up @@ -188,45 +188,45 @@ on GitHub. Just push the branches up to GitHub.

1. When `merge.renamelimit` is set to a large value, the output of the
`git merge` command may have several lines like:
- CONFLICT (rename/delete): ... in master renamed to ... in HEAD. Version
- CONFLICT (rename/delete): ... in main renamed to ... in HEAD. Version
HEAD ... left in tree.
- CONFLICT (rename/delete): ... in master renamed to ... in HEAD. Version
master ... left in tree.
- CONFLICT (rename/delete): ... in main renamed to ... in HEAD. Version
main ... left in tree.

If the version in HEAD is left in tree, it is very likely a valid change -
the file may have been moved. If the version in `master` is left in tree,
the file may have been moved. If the version in `main` is left in tree,
the files may be valid files that have been added as part of Checked C
support:
- `llvm/projects/checkedc-wrapper/lit.site.cfg.py`
- `llvm/projects/checkedc-wrapper/lit.cfg.py`

Others may need more investigation. For example, in the LLVM/Clang 11 to 12
merge, two files which were reported by git as "Version master ... left in
merge, two files which were reported by git as "Version main ... left in
tree" were old versions lying around that needed to be deleted:
- `clang/include/clang/StaticAnalyzer/Core/PathSensitive/SMTAPI.h`
- `clang/include/clang/AST/TypeNodes.def`

2. While resolving merge conflicts, it is a good idea to have three reference
code snapshots to perform diffs of individual files to help distinguish between
checkedc-specific changes and llvm-11-to-12 changes:
- The `master` branch of the `checkedc-llvm-project` repository at the commit hash
which was merged into `updated_baseline_master_12`.
- The `main` branch of the `checkedc-clang` repository at the commit hash
which was merged into `updated_baseline_main_12`.
- The pristine LLVM/Clang source at &lt;branch-point-of-11-on-main&gt;
- The pristine LLVM/Clang source at &lt;branch-point-of-12-on-main&gt;

The description of the three snapshots above holds only for the initial
merge from LLVM 11 to 12 in phase 1 step 6. For a merge of additional
Checked C feature development in phase 1 step 8, here are the relevant
snapshots and their commit hashes, which we get from the in-progress merge:
- A snapshot of branch `updated_baseline_master_12` after phase 1 step 7, or
- A snapshot of branch `updated_baseline_main_12` after phase 1 step 7, or
an earlier iteration of step 8. The commit hash that corresponds to this
snapshot is `HEAD` - use command `git rev-parse HEAD` to dump the commit
hash.
- A snapshot of the `master` branch that participated in the previous merge
- A snapshot of the `main` branch that participated in the previous merge
that produced the above snapshot. The commit hash that corresponds to this
snapshot is the common ancestor - use command
`git merge-base HEAD MERGE_HEAD` to dump the commit hash.
- A snapshot of the current `master` branch. The commit hash that
- A snapshot of the current `main` branch. The commit hash that
corresponds to this is `MERGE_HEAD` - use command `git rev-parse MERGE_HEAD`
to dump the commit hash.

Expand Down

0 comments on commit 33c5d72

Please sign in to comment.