Jon Ross-Perkins
6f6e46ef57
The WORKSPACE file is deprecated; support is already off by default, and it'll be removed in the next major bazel release. Our main dependency is tree-sitter, and I'm trying to address that here. We're currently using https://github.com/elliottt/rules_tree_sitter, but that hasn't been updated in a couple years, meaning it lacks MODULE.bazel support. In the registry, there's https://registry.bazel.build/modules/tree-sitter-bazel, but this is only the *parser* libraries of tree-sitter, not the *generator*. I'm using it for that much, at least. For the *generator*, which transforms grammar.js to parser.c/h, I'm just requiring a non-hermetic invocation (i.e., people who want to work on it will need to install tree-sitter; see the README.md updates). I tried running it manually, but parser.c is about 600 KB; pre-commit rejects files that large and I don't think an exception makes sense to override for this (it'd probably also grow substantially if the grammar were updated to cover more syntax). In order to make the non-hermetic call not break "bazel build //..." for most developers, I'm marking most targets in the package as manual. Note, I did look long and hard at using `aspect_rules_js`/`rules_nodejs` to invoke npm. This took a lot of time, and I have a commit that's mostly working, except I hit a point where it uses `declare_symlink` which we disallow for compatibility reasons (commit "Lots of work for figuring out rule_js uses declare_symlink" on the PR). As a consequence, I think we can't use the primary supported ways to have hermetic npm calls. Also, `treesitter` -> `tree_sitter` because it's generally called `tree-sitter`, two words. We even had a `treesitter/src/tree_sitter` directory so it's a bit inconsistent. As far as bugs here, the parser library breaks bazel queries, e.g. the error: ``` ERROR: Evaluation of query "somepath(//..., @llvm-project//third-party/unittest:gtest)" failed: preloading transitive closure failed: no such package '@@[unknown repo 'platforms' requested from @@tree-sitter-bazel+]//': The repository '@@[unknown repo 'platforms' requested from @@tree-sitter-bazel+]' could not be resolved: No repository visible as '@platforms' from repository '@@tree-sitter-bazel+' ``` I'm just excluding tree_sitter from queries where I can to work around the error.
Docs
This directory contains current, accepted documentation underpinning Carbon. These documents cover all aspects of Carbon ranging from the project down to detailed designs for specific language features.
If you're trying to learn more about Carbon, we recommend starting at
/README.md.
Design
Carbon language's design and rationale are documented in the
design/ directory. This documentation is intended to
support the following audiences:
- People who wish to determine whether Carbon would be the right choice for a project compared to other existing languages.
- People working on the evolution of the Carbon language who wish to understand the rationale and motivation for existing design decisions.
- People working on a specification or implementation of the Carbon language who need a detailed understanding of the intended design.
- People writing Carbon code who wish to understand why the language rules are the way they are.
This is in contrast to proposals, which document the individual decisions that led to this design (along with other changes to the Carbon project), including the rationale and alternatives considered.
Project
The project/ directory contains project-related
documentation for Carbon, including:
- goals, and the principles and roadmap derived from those goals,
- how the project works, and
- how to contribute.
Guides
The guides/ directory contains to-be-written end-user
documentation for developers writing programs in Carbon.
Spec
The spec/ directory contains the to-be-written formal
specification of the Carbon language. This is for implementers of compilers or
other tooling. This is intended to complement the interactive
language explorer tool.