I'm trying to use this just to document the de facto state. This is
linked to #4246, but I'm trying to keep the two arranged to allow
independent merges.
Trying to pull in key elements of #3762, #3763, and #3980 (decl matching
and `extern`, essentially). These aren't specific to any particular
declaration type, but are common to entities, so suggesting a new doc
oriented on that.
There's probably more that could be said here, I'm just focused on
getting the recent formal discussion mirrored into the design.
---------
Co-authored-by: josh11b <15258583+josh11b@users.noreply.github.com>
Demo site: https://jonmeow.carbon-lang.dev/
I'm trying to keep work under the `/website` subdirectory so that the
misc files don't interfere with unrelated views of the repository. The
`prebuild.py` script does some work to move things around and add
frontmatter, helping the jekyll generation.
I'm using the "just-the-docs" theme because I think it's a decent match
for what we want, and getting jekyll up and running with it wasn't too
difficult. Note #1526 proposed using Docusaurus; I started out there,
but was having trouble getting it working with newer versions. The
plugins in particular I got stuck trying to make work, which sent me
looking for options that we could have working with less customization.
I do lean towards jekyll though, because it's what GH uses so hopefully
we can get a more consistent experience.
Having a website has been approved for a while under #1492, but hasn't
been a priority. I'm mainly doing this because I want to just be able to
point people to carbon-lang.dev and have easy links that way.
---------
Co-authored-by: Chandler Carruth <chandlerc@gmail.com>
Update the operator precedence to achieve a few goals:
- Form operators into groups which behave similarly
- Make the group of operators ("top-level operators") that capture
everything to the right, like `if`...`then`...`else`, behave similarly
to the left, so that rearranging expressions won't change how they
group.
- Add the `where` operator, used to specify constraints on facet types,
to the precedence chart, to define how it interacts with other
operators.
- Make the operator precedence diagram prettier, so that it eventually
can be made into a poster that Carbon programmers can hang on their
walls.
---------
Co-authored-by: Josh L <josh11b@users.noreply.github.com>
Co-authored-by: Richard Smith <richard@metafoo.co.uk>
Also a small pass on workflow names.
Note, I'm a little concerned that the test/nightly release/pre-commit
endpoints may be fragile. At the same time, it's also where it may be
most useful, to prevent network access by arbitrary test code. I think
this is imperfect, but maybe we can try it out and see if it's much of
an issue.
Note, the discord wiki action is currently broken, this should fix it.
I was considering making a "/bazel" alias for this, but I'm really on
the fence about whether that's a good choice. However, I do think this
is good to have to simplify installs.
Fixes#3071 and #3896
Proposal for how Carbon version numbers work:
- A single version across language, standard library, compiler, linker,
etc.
- Semantic Versioning (SemVer) based
- Details of how SemVer criteria for major, minor, and patch should
apply to
Carbon
- Details of how we will operate before 1.0 and how this connects to
Carbon's
milestones
- Directional guidance for future work including post-1.0 versions, LTS
versions, and standardization
---------
Co-authored-by: Richard Smith <richard@metafoo.co.uk>
Also makes an alias so that this is easier to find. Verified that
running the alias still finds prelude files.
Note the actual target is printed when building (although a symlink is
also created, using that symlink confuses file-finding).
```
╚╡bazel build :carbon
...
Target //toolchain/install:prefix_root/bin/carbon up-to-date:
bazel-bin/toolchain/install/prefix_root/bin/carbon
```
The current approach was done to work-around a limitation that we can
only have a single link per box, but is unscalable. Instead have a
single link to a new sections of the document that describes the box,
and has multiple links.
---------
Co-authored-by: Josh L <josh11b@users.noreply.github.com>
Co-authored-by: Richard Smith <richard@metafoo.co.uk>
Following discussions around #3958, try to provide more specific
semantics. Note we currently don't follow this everywhere, particularly
in AddInst calls, but the intent is to shift. Per discussion, designated
initializers are preferred when possible. And the
`google-readability-casting` diagnostics are poor, but with this may
primarily flag cases which should be using a different constructor
syntax, so are just a rocky way to get there.
---------
Co-authored-by: Richard Smith <richard@metafoo.co.uk>
Replace image file in /docs/images/ directory and update the svg editing
document to reflect the change to package syntax from proposal #3927Closes#3969
Update broken links to aid in following links while perusing the
documentation. Closes#3778
I don't imagine I got every one of these right. Some 404s may be
reported due to permissions.
Using the lychee command in #3778, only the following link is reported
as not found, but it's just a permission issue:
```
[proposals/p1367.md]:
✗ [404] https://github.com/carbon-language/carbon-lang/settings/access | Failed: Network error: Not Found
```
I tried to get it down to as few as possible, partially so that future
link scans won't run into repeat errors.
---------
Co-authored-by: Jon Ross-Perkins <jperkins@google.com>
Co-authored-by: Carbon Infra Bot <carbon-external-infra@google.com>
On macOS, Homebrew recommends `pipx` to install Python binaries, or
installing `pre-commit` directly, since it is available.
Here is the message in full.
```console
❯ pip3 install pre-commit
error: externally-managed-environment
× This environment is externally managed
╰─> To install Python packages system-wide, try brew install
xyz, where xyz is the package you are trying to
install.
If you wish to install a non-brew-packaged Python package,
create a virtual environment using python3 -m venv path/to/venv.
Then use path/to/venv/bin/python and path/to/venv/bin/pip.
If you wish to install a non-brew packaged Python application,
it may be easiest to use pipx install xyz, which will manage a
virtual environment for you. Make sure you have pipx installed.
```
~~Also, unless there is a compelling reason to install a particular 3.x
version of Python, it may be better to let Homebrew use whatever version
people may already have installed (or let it automatically install the
version they've tested).~~
Here are the details of the pre-commit Homebrew package:
```
❯ brew info pre-commit
==> pre-commit: stable 3.6.2 (bottled), HEAD
Framework for managing multi-language pre-commit hooks
https://pre-commit.com/
/opt/homebrew/Cellar/pre-commit/3.6.2 (679 files, 9.9MB) *
Poured from bottle using the formulae.brew.sh API on 2024-03-08 at 22:22:11
From: https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/p/pre-commit.rb
License: MIT
==> Dependencies
Required: libyaml ✔, python@3.12 ✔
```
Installing directly with Homebrew is a supported option in the
pre-commit documentation. https://pre-commit.com/#install
Offers a more precise apples-to-apples language comparison. Replaces the
non-portable `M_PI` and removes the extraneous arg parameters. It does
use C++23, so I can understand if that's unacceptable for the time
being.
Improve the exposition of the design changes from #3646 to integrate
better into the overall description of member access design.
This fixes the incorrect description of the rules for `->` by instead
relying on the general rule that `->` is rewritten to use `*` and `.`
before any other processing is done, and generally makes
*integer-literal* names be less of a special case.
Add support for extracting elements of a tuple by their numerical index.
Also formally add the well-established basic syntactic and semantic
rules for
tuples, for which we have had leads issues but no proposal, into the
design.
This should also unblock our switch to C++20 and other improvements.
There are three core parts of the change --
1) Updating our infrastructure to fetch and find Clang-16.
2) Updating our documentation to reflect this and help folks with any
system issues they encounter.
The infrastructure change is unfortunately tricky. We can't get Clang 16
easily on GitHub's runner images, and in the past we've had persistent
problems with flakiness when our actions download this much during their
runs. Due to the flakiness, we've previously removed all downloading of
dependencies outside of Bazel itself, and added retry loops around Bazel
specifically to overcome flaky downloads.
This change tries to address these problems by populating the Clang and
LLVM toolchain in a place that we can then cache using the built-in
GitHub action caching infrastructure. This seems like by far the least
likely to flake way of downloading extra things into our runs. And since
these are relatively slow moving dependencies, we should populate this
cache very, very rarely.
For Linux, this downloads the binary release artifact from GitHub,
prunes out large parts of it that we don't need, and then caches this as
a local toolchain. This proves both small and fast.
For macOS, this uses a trick to cache the destination of Homebrew
installs. It unfortunately caches the *entire* Homebrew installation
though, and so it also goes to some lengths to prune and minimize how
much is installed from Homebrew. The result is "only" a 2gb cache image.
Because of the size and slower download and filesystem, the macOS runs
see a 1 - 2 minute slowdown.
We might extend the Linux infrastructure here usefully if we want to
test multiple LLVM versions. We might also extend the macOS version to
get a cheaper way to prune parts of the system and free up disk space,
or to cache other Homebrew installed tools if needed.
Last but not least, this brought to the forefront an issue with our C++
toolchain integration which relied on a specific CMake build option
being set in the LLVM toolchain install. This option isn't used in the
official release artifacts. Instead, switch to a more robust approach to
linking libc++abi statically that shouldn't have these problems.
Beyond the infrastructure changes, this also updates the documentation
to reflect requiring Clang 16 or newer, and adds some extra tips for
folks that are missing this.
The documentation is also updated to address a problem with getting the
right libc++abi files installed to support the more robust linking
strategy. This may reduce the problems we've seen in the past around
libc++abi and linking on other Linux distros as well.
---------
Co-authored-by: josh11b <josh11b@users.noreply.github.com>
This PR is changing the color of the var keyword in the `PrintTotalArea`
source example which is referenced in the README. The original color was
white and changed to `#FF7B72`.
---------
Co-authored-by: jonmeow <jperkins@google.com>
We propose a roadmap for 2024 focused on a working Carbon toolchain that
supports Carbon ↔ C++ interop.
---------
Co-authored-by: Jon Ross-Perkins <jperkins@google.com>
Co-authored-by: Richard Smith <richard@metafoo.co.uk>
Proposal to focus implementation effort for the next 1-2 years on the
Carbon
toolchain instead of the explorer. This will impact the explorer in a
few ways:
- We will keep the explorer's code in place, building, and passing its
basic
tests. It can remain a good baseline for exploring Carbon's language
features.
- We won't prioritize expanding the explorer's coverage of Carbon
features or
other improvements -- it is good enough for what we need until the
toolchain
catches up.
- We will stop actively fuzzing and expanding test coverage for the
explorer.
- Eventually, when we want to resume work on the explorer, we'll
evaluate the
best platform to build on -- the current explorer codebase or on top of
the
toolchain's semantic IR.
Also tries to update the core readme and contributing docs to reflect
this.
This Pull Request added support for Bazel installation and setup in the
contribution_tools.md file un the docs directory. It added a link to the
releases page of the bazel repository for debian/ubuntu users to
download the binary and execute the commands provided in the
documentation.
Closes#3439
The version of `flake8` was too old to support with Python 3.12 -- there
is new F-string support that caused false positives sadly. The updated
version has fixes for all of these.
This in turn updates codespell which has picked up several new fixes
that actually fire in our code, so also fix everything. While we don't
do more in-depth updates to old proposals, similar to simply fixing
broken links, fixing automatically detected typos seems scalable and
fine.
All edits were automatically generated here.
- Require namespace members be declared in the same name scope as the
namespace is declared.
- Allow binding patterns to directly declare names in namespaces.
- Disallow using different namespaces in the same binding pattern.
---------
Co-authored-by: Chandler Carruth <chandlerc@gmail.com>
Co-authored-by: Richard Smith <richard@metafoo.co.uk>
When there is no `package` directive, default to `Main//default api`
instead of
`Main//default impl`. This means:
- The extension will be `.carbon`, not `.impl.carbon`.
- There can only be one such file when compiling.
---------
Co-authored-by: Chandler Carruth <chandlerc@gmail.com>
Continued from part 1: #3231. Second step updating
`docs/design/generics/details.md`. There remains some work to
incorporate proposal #2200.
- The biggest changes are incorporating much of the text of proposals:
- #2173
- #2687
- It incorporates changes from proposals:
- #989
- #1178
- #2138
- #2200
- #2360
- #2964
- #3162
- It also updates the text to reflect the latest thinking from leads
issues:
- #996
- #2153 -- most notably deleting the section on `TypeId`.
- Update to rule for prioritization blocks with mixed type structures
from [discussion on
2023-07-18](https://docs.google.com/document/d/1gnJBTfY81fZYvI_QXjwKk1uQHYBNHGqRLI2BS_cYYNQ/edit?resourcekey=0-ql1Q1WvTcDvhycf8LbA9DQ#heading=h.7jxges9ojgy3)
- Adds reference links to proposals, issues, and discussions relevant to
the text.
- Also tries to use more precise language when talking about
implementations, to avoid confusing `impl` declaration and definitions
with the `impls` operator used in `where` clauses, an issue brought up
in
- #2495
- #2483
---------
Co-authored-by: Richard Smith <richard@metafoo.co.uk>
Includes proposals:
- #990
- #2188
- #2138
- #2200
- #2360
- #2760
- #2964
- #3162
Also tries to use more precise language when talking about:
- implementations, to avoid confusing `impl` declaration and definitions
with the `impls` operator used in `where` clauses, an issue brought up
in #2495 and #2483;
- "binding patterns", like `x: i32`, and "bindings" like `x`.
---------
Co-authored-by: Chandler Carruth <chandlerc@gmail.com>
First step in updating `docs/design/generics/details.md`. It
incorporates changes from proposals: #989#2138#2173#2200#2360#2964#3162 , but there are still more changes from those proposals to be
made.
It also switches away from suggesting static-dispatch witness tables,
and creates an appendix to describe that decision.
---------
Co-authored-by: Richard Smith <richard@metafoo.co.uk>
Rationale: this convention avoids forcing closely-related code to be far
apart in the namespace hierarchy, and vice versa. By the same token, it
makes the namespace hierarchy more consistent with the directory
hierarchy.
David Blaikie
Jon Ross-Perkins
Brymer Meneses
Rajat Roy
Patrick Johnston
cui fliter
Rayyan Kandjonmeow
Nicolas Gonzalez
Christopher Di Bella
Sree Dananjay S
Geoff Romer
Piyush Udhao