* docs(std.math): elaborate on difference between absCast and absInt
* docs(std.rand.Random.weightedIndex): elaborate on likelihood
I think this makes it easier to understand.
* langref: add small reminder
* docs(std.fs.path.extension): brevity
* docs(std.bit_set.StaticBitSet): mention the specific types
* std.debug.TTY: explain what purpose this struct serves
This should also make it clearer that this struct is not supposed to provide unrelated terminal manipulation functionality such as setting the cursor position or something because terminals are complicated and we should keep this struct simple and focused on debugging.
* langref(package listing): brevity
* langref: explain what exactly `threadlocal` causes to happen
* std.array_list: link between swapRemove and orderedRemove
Maybe this can serve as a TLDR and make it easier to decide.
* PrefetchOptions.locality: clarify docs that this is a range
This confused me previously and I thought I can only use either 0 or 3.
* fix typos and more
* std.builtin.CallingConvention: document some CCs
* langref: explain possibly cryptic names
I think it helps knowing what exactly these acronyms (@clz and @ctz) and
abbreviations (@popCount) mean.
* variadic function error: add missing preposition
* std.fmt.format docs: nicely hyphenate
* help menu: say what to optimize for
I think this is slightly more specific than just calling it
"optimizations". These are speed optimizations. I used the word
"performance" here.
- Add an example of iterating over consecutive integers using the
range syntax
- Add an example of iterating over multiple objects
- Update the "nested break" and "nested continue" tests to use the
range syntax, instead of a temporary array
- Fix usage string `--skip-code-test` to `--skip-code-tests`.
- Added a token `{#additonal_option|-rdynamic#}` which introduce arbitrary flag to `build-exe/obj/lib` example.
- Fix wasm freestanding example, it now needs explicit export symbols to work.
* @workItemId returns the index of the work item in a work group for a
dimension.
* @workGroupId returns the index of the work group in the kernel dispatch for a
dimension.
* @workGroupSize returns the size of the work group for a dimension.
These builtins are mainly useful for GPU backends. They are currently only
implemented for the AMDGCN LLVM backend.
Make the termColor function more robust, ensuring that the generated
HTML classes are more consistent and that they are supported in the CSS.
Add documentation about the ANSI codes generated by Zig, and remove the
previous comment with the supported colors.
Improve test coverage for the termColor function, and move the tests at
the end of the file before the printShell tests.
Rename the "term color" test to "term supported colors" and add an
additional "term output from zig" test, using test data generated from
the Zig compiler.
Update the langref.html.in CSS to use the new names and remove incorrect
or obsolete colors like .t0_1, .t37 and .t37_1.
Fix support for the 1m color. Change font-weight to normal for the kbd
element, to avoid both the command (like `zig build-exe`) and the first
line of the error message having a bold font.
Rename the "shell parsed" test to "printShell".
Line support in printShell breaks the support to terminal colors, when a
color is active over multiple lines. An example is when printing
reference traces.
Remove line support in printShell, since they are not really necessary
like in printSourceBlock.
In genHtml, remove an empty line when printing the execution of the
executable generated by `zig build-exe`.
Update the "shell parsed" tests.
Remove the call to log.emerg, since it is no longer supported.
Add an extra space after "--build-option1 \", as documented.
Fixes#13280
This should add all remaining missing return types to all builtin
functions.
For @clz, @ctz, and @popCount it uses anytype for the lack of a better
alternative. We already use this return type for other builtin functions in the langref
to indicate that the type is not always the same.
It is not possible to use anytype as the return type for regular
functions but builtin functions are special.
In 41 (Undefined Behavior) . 5 (Integer Overflow) . 3 (Builtin Overflow Functions), it is stated that
> These builtins return a bool of whether or not overflow occurred, as well as returning the overflowed bits:
> * @addWithOverflow
> * @subWithOverflow
> * @mulWithOverflow
> * @shlWithOverflow
but in their definition says that it returns a `tuple`/`struct`.
Example;
`@addWithOverflow(a: anytype, b: anytype) struct { @TypeOf(a, b), u1 }`
Co-authored-by: zooster <r00ster91@proton.me>
This introduces a new builtin function that compiles down to something that results in an illegal instruction exception/interrupt.
It can be used to exit a program abnormally.
This implements the builtin for all backends.
* Scan from line start when finding tag in tokenizer
This resolves a crash that can occur for invalid bytes like carriage
returns that are valid characters when not parsed from within literals.
There are potentially other edge cases this could resolve as well, as
the calling code for this function didn't account for any potential
'pending_invalid_tokens' that could be queued up by the tokenizer from
within another state.
* Fix carriage return crash in multiline string
Follow the guidance of #38:
> However CR directly before NL is interpreted as only a newline and not part of the multiline string. zig fmt will delete the CR.
Zig fmt already had code for deleting carriage returns, but would still
crash - now it no longer does so. Carriage returns encountered before
line-feeds are now appropriately removed on program compilation as well.
* Only accept carriage returns before line feeds
Previous commit was much less strict about this, this more closely
matches the desired spec of only allow CR characters in a CRLF pair, but
not otherwise.
* Fix CR being rejected when used as whitespace
Missed this comment from ziglang/zig-spec#83:
> CR used as whitespace, whether directly preceding NL or stray, is still unambiguously whitespace. It is accepted by the grammar and replaced by the canonical whitespace by zig fmt.
* Add tests for carriage return handling
Some examples using {#syntax_block|zig|...#} either have a valid syntax
or it is easy to make the syntax valid. Update these example to use
{#code_begin|syntax|...#}.
Remove extra whitespace in the error_union_parsing_u64.zig example.
Replace size_t with usize in the call_malloc_from_zig.zig example.
Commit 40f5e5dfc6 ("CLI: introduce -fsingle-threaded/
-fno-single-threaded", 2021-12-01) removed the `--single-threaded`
option, but didn't update all mentions of it.
$ zig version
0.11.0-dev.1568+c9b957c93
$ zig build-exe --help | grep single
-fsingle-threaded Code assumes there is only one thread
-fno-single-threaded Code may not assume there is only one thread
$ zig build-exe --single-threaded foo.zig
error: unrecognized parameter: '--single-threaded'
PR #10610 addressed most of the points from #1854. This
additional paragraph and examples covers the OMISSIONS section
clarifying issues about indexing into non-ASCII strings (whether valid
UTF-8 or not). I think this finally closes#1854.
In the "Type Coercion" section, rename:
- Coercion Float to Int => Float to Int
- unions and enums => Unions and Enums
- tuples to arrays => Tuples to Arrays
In the "C Translation CLI" section, move the paragraph inside the p
element.
The current HTML is valid, but, as an example, a paragraph outside a p
element is not handled correctly by the browser Inspect tool.
In commit 3542dbf0ea (langref: add section numbers) I accidentally
added an extra closing curly bracket at the end of the style element.
Sorry for not validating the HTML file before creating the PR.
Update the genToc funtion to make the name required in the Code node,
and add an additional optional field for the expected error, to use with
test_err, test_safety and obj_err.
Update langref.html.in to ensure all code blocks have a name that
- is unique, so that a doctest can be identified by it
- is descriptive
For test, test_err and test_safefy, ensure that the doctest name starts
with "test_", excluding doctests in the "Zig Test" section and doctests
that are imported by other doctests.
Ensure that the indentation of code_begin and code_end blocks are
consistent.
Fix a typo in pointer_arthemtic.
In a syntax_block the code always start on a separate code, expect for
C, JavaScript, Peg and with Zig inline assembly.
Ensure that the code starts on a separate line, even in cases where
there is only one line.
Ensure that the end_syntax_block is always on a separate line and that
the indentation is consistent.
The current compiler ignores the UTF-8 BOM if it is at the start of the
file, and disallows it anywhere else. Document it in the Source Encoding
section.
Add the new addrspace keyword in the Keyword Reference section, without
documentation.
Move the linksection keyword in order to keep the keywords list sorted.
The deallocations of the process arguments are unnecessary, since the
memory will be deallocated by arena.deinit().
The deallocations are incorrect, since ArgIterator.next() returns a
slice pointing to the iterator's internal buffer, that should be
deallocated with args_it.deinit().
When reading a document with nested sections, it is not easy to discover
the depth of the current section.
Add support for nested section numbers, from the h2 to the h4 heading,
in the format "lv1. ", "lv1.lv2. ", "lv1.lv2.lv3. ". The "Zig Version"
and "Table of Content" sections are excluded.
The section numbers are implemented in CSS, with the CSS rules declared
inside a @media rule. Currently the @media rule targets all media.
This was a poor naming choice; these are parameters, not arguments.
Parameters specify what kind of arguments are expected, whereas the arguments are the actual values passed.
Add a missing ReleaseSmall when describing unreachable in the try
section and the unreachable entry in the Keyword Reference section.
Additionally, transform Debug, ReleaseSafe, ReleaseFast and ReleaseSmall
into links in the try section.
Co-authored-by: Andrew Kelley <andrew@ziglang.org>
Currently, the test_fn_reflection.zig doctest has an example of
.Fn.is_var_args. This example can confuse the reader, since there is no
documentation about variadic functions and is_var_args is mainly used in
the compiler.
Remove the example with .Fn.is_var_args and add instead examples with
.Fn.return_type and .Fn.is_generic.
In the slice_bounds.zig doctest, the code "const slice = array[2..4]" is
incorrect, since the actual type is a pointer to an array, instead of a
slice.
Use a runtime know value to slice the array.
In the slices.zig doctest, the code
`const all_together_slice = all_together[0..]` is incorrect, since the
actual type is a pointer to an array, instead of a slice.
Use a runtime-known value to slice the array.
In the next "slice pointer" test, clarify that slicing a slice to
produce a pointer to an array, requires comptime-known indexes, not just
constant indexes.
Split the original `defer.zig` doctest into 3 doctest:
1. Document the defer keyword
2. Document that the return statement is not allowed inside a defer
expression
3. Document the errdefer keyword
Replace "method" with "expression" in the text `defer method`.
Several <em> elements where added inside a shell node in the
Using--target-and--cflags section. Remove them, since they are not
supposed to be handled by codegen.
For the original commit, see
0c091feb5 (Improve HTML semantics and a11y of language reference).
Fixes#13846
This commit removes async/await/suspend/resume from the language
reference, as that feature does not yet work in the self-hosted
compiler.
We will be regressing this feature temporarily. Users of these language
features should stick with 0.10.x with the `-fstage1` flag until they
are restored.
See tracking issue #6025.
The packed struct example was mistakenly applying endianness where it
shouldn't have been. This wasn't being caught because we don't currently
test the examples on Big-endian systems.
I updated the test to remove the endianness where it didn't apply, and
added a new part of the test to demonstrate when it would apply.
* When a field starts at some bit offset within a byte you need to load
starting from that byte and shift, not starting from the next byte,
so a rounded-down divide is required here, not a rounded-up one.
* Remove paragraph from doc that no longer relates to anything.
Closes#12363
Storing defers this way has the benefits that the defer doesn't get
analyzed multiple times in AstGen, it takes up less space, and it
makes Sema aware of defers allowing for 'unreachable else prong'
error on error sets in generic code.
The disadvantage is that it is a bit more complex and errdefers with
payloads now emit a placeholder instruction (but those are rare).
Sema.zig before:
Total ZIR bytes: 3.7794370651245117MiB
Instructions: 238996 (2.051319122314453MiB)
String Table Bytes: 89.2802734375KiB
Extra Data Items: 430144 (1.640869140625MiB)
Sema.zig after:
Total ZIR bytes: 3.3344192504882812MiB
Instructions: 211829 (1.8181428909301758MiB)
String Table Bytes: 89.2802734375KiB
Extra Data Items: 374611 (1.4290275573730469MiB)
Before, native glibc and dynamic linker detection attempted to use the
executable's own binary if it was dynamically linked to answer both the
C ABI question and the dynamic linker question. However, this could be
problematic on a system that uses a RUNPATH for the compiler binary,
locking it to an older glibc version, while system binaries such as
/usr/bin/env use a newer glibc version. The problem is that libc.so.6
glibc version will match that of the system while the dynamic linker
will match that of the compiler binary. Executables with these versions
mismatching will fail to run.
Therefore, this commit changes the logic to be the same regardless of
whether the compiler binary is dynamically or statically linked. It
inspects `/usr/bin/env` as an ELF file to find the answer to these
questions, or if there is a shebang line, then it chases the referenced
file recursively. If that does not provide the answer, then the function
falls back to defaults.
This commit also solves a TODO to remove an Allocator parameter to the
detect() function.
saying []T is a pointer is confusing because zig docs say there are two types of pointers (*T and [*]T). It is more clear to say that []T is a slice type which contains a [*]T pointer and a length.
Co-authored-by: Philipp Lühmann <47984692+luehmann@users.noreply.github.com>
This reverts commit 7cbd586ace.
This is causing a fail to build from source:
```
./lib/std/fmt.zig:492:17: error: cannot format optional without a specifier (i.e. {?} or {any})
@compileError("cannot format optional without a specifier (i.e. {?} or {any})");
^
./src/link/MachO/Atom.zig:544:26: note: called from here
log.debug(" RELA({s}) @ {x} => %{d} in object({d})", .{
^
```
I looked at the code to fix it but none of those args are optionals.
The current phrasing is vague; it is unclear whether it is demonstrating an example of the type of permitted behavior, from which the rule set must be extrapolated, or it is stating that this restriction only applies to the relationship between integers and bare structs.
Rename all references of sparcv9 to sparc64, to make Zig align more with
other projects. Also, added new function to convert glibc arch name to Zig
arch name, since it refers to the architecture as sparcv9.
This is based on the suggestion by @kubkon in PR 11847.
(https://github.com/ziglang/zig/pull/11487#pullrequestreview-963761757)
stage2: change logic for detecting whether the main package is inside
the std package. Previously it relied on realpath() which is not portable.
This uses resolve() which is how imports already work.
* stage2: fix cleanup bug when creating Module
* flatten lib/std/special/* to lib/*
- this was motivated by making main_pkg_is_inside_std false for
compiler_rt & friends.
* rename "mini libc" to "universal libc"
The reason for having `@tan` is that we already have `@sin` and `@cos`
because some targets have machine code instructions for them, but in the
case that the implementation needs to go into compiler-rt, sin, cos, and
tan all share a common dependency which includes a table of data. To
avoid duplicating this table of data, we promote tan to become a builtin
alongside sin and cos.
ZIR: The tag enum is at capacity so this commit moves
`field_call_bind_named` to be `extended`. I measured this as one of
the least used tags in the zig codebase.
Fix libc math suffix for `f32` being wrong in both stage1 and stage2.
stage1: add missing libc prefix for float functions.
For those souls looking for a zig `size_t` equivalent, and not
lucky/educated enough (that was me yesterday) to know it's the same as
`uintptr_t`.
From a recent discussion on IRC.
Two major changes here:
1. We store the CWD as a simple `[]const u8` and lookup Preopens for
every absolute or CWD-referenced file operation, based on the
Preopen with the longest match (i.e. most specific path)
2. Preorders are normalized to POSIX absolute paths at init time.
Behavior depends on the "cwd_root" parameter of `initPreopensWasi`:
`cwd_root` is used for any Preopens that start with "."
For example:
"./foo/bar" - inits to -> "{cwd_root}/foo/bar"
"foo/bar" - inits to -> "/foo/bar"
"/foo/bar" - inits to -> "/foo/bar"
`cwd_root` must be an absolute path.
Using "/" as `cwd_root` gives behavior similar to wasi-libc.
* make it always return a fully qualified name. stage1 is inconsistent
about this.
* AstGen: fix anon_name_strategy to correctly be `func` when anon type
creation happens in the operand of the return expression.
* Sema: implement type names for the "function" naming strategy.
* Put "enum", "union", "opaque", or "struct" in place of "anon" when
creating respective anonymous Decl names.
* std.testing: add `expectStringStartsWith`. Didn't end up using it
after all.
Also this enables the real test runner for stage2 LLVM backend (sans
wasm32) since it works now.
I hit the "quotes in an RSP file" issue when trying to compile gRPC using
"zig cc". As a fun exercise, I decided to see if I could fix it myself.
I'm fully open to this code being flat-out rejected. Or I can take feedback
to fix it up.
This modifies (and renames) _ArgIteratorWindows_ in process.zig such that
it works with arbitrary strings (or the contents of an RSP file).
In main.zig, this new _ArgIteratorGeneral_ is used to address the "TODO"
listed in _ClangArgIterator_.
This change closes#4833.
**Pros:**
- It has the nice attribute of handling "RSP file" arguments in the same way it
handles "cmd_line" arguments.
- High Performance, minimal allocations
- Fixed bug in previous _ArgIteratorWindows_, where final trailing backslashes
in a command line were entirely dropped
- Added a test case for the above bug
- Harmonized the _ArgIteratorXxxx._initWithAllocator()_ and _next()_ interface
across Windows/Posix/Wasi (Moved Windows errors to _initWithAllocator()_
rather than _next()_)
- Likely perf benefit on Windows by doing _utf16leToUtf8AllocZ()_ only once
for the entire cmd_line
**Cons:**
- Breaking Change in std library on Windows: Call
_ArgIterator.initWithAllocator()_ instead of _ArgIterator.init()_
- PhaseMage is new with contributions to Zig, might need a lot of hand-holding
- PhaseMage is a Windows person, non-Windows stuff will need to be double-checked
**Testing Done:**
- Wrote a few new test cases in process.zig
- zig.exe build test -Dskip-release (no new failures seen)
- zig cc now builds gRPC without error
* Create Vector language documentation
Main changes to docs:
1. Create brief documentation on Zig vector types with code example
2. Get rid of the SIMD sub-heading under the main Vectors heading,
and update links accordingly
3. Add an example to the `@shuffle` docs
`getExternalExecutor` is moved from `std.zig.CrossTarget` to
`std.zig.system.NativeTargetInfo.getExternalExecutor`.
The function also now communicates a bit more information about *why*
the host is unable to execute a binary. The CLI is updated to report
this information in a useful manner.
`getExternalExecutor` is also improved to detect such patterns as:
* x86_64 is able to execute x86 binaries
* aarch64 is able to execute arm binaries
* etc.
Added qemu-hexagon support to `getExternalExecutor`.
`std.Target.canExecBinaries` of is removed; callers should use the more
powerful `getExternalExecutor` instead.
Now that `zig test` tries to run the resulting binary no matter what,
this commit has a follow-up change to the build system and docgen to
utilize the `getExternalExecutor` function and pass `--test-no-exec`
in some cases to avoid getting the error.
Additionally:
* refactor: extract NativePaths and NativeTargetInfo into their own
files named after the structs.
* small improvement to langref to reduce the complexity of the `callconv`
expression in a couple examples.
Updates the Language Reference sections: Comments, Values, and Zig Test.
Zig Test section moved down with the goal "make sure it can be read top to
bottom sensibly" in mind (issue #1524).
Comments and Values section examples changed test declarations to a main
function and expect statement to print statements.
A print statement was added to the "String Literals and Unicode Code Point"
section's example to demonstrate the "u" format specifier.
Zig Test Section:
* Addresses the question: "How does the syntax work?".
* Partially answers the question: "What can I do with the zig test tool?" but
should be sufficient to understand the examples in all of this document.
* Addresses the question: "How does a top-level test block differ from a function definition?"
* Provides a example to run multiple test.
Lacks clear definitions of containers, top-level, order independence, lazy
analysis, resolve, reference.
GitHub Issues: #8221, #8234
* Remove the builtins `@addWithSaturation`, `@subWithSaturation`,
`@mulWithSaturation`, and `@shlWithSaturation` now that we have
first-class syntax for saturating arithmetic.
* langref: Clarify the behavior of `@shlExact`.
* Ast: rename `bit_shift_left` to `shl` and `bit_shift_right` to `shr`
for consistency.
* Air: rename to include underscore separator with consistency with
the rest of the ops.
* Air: add shl_exact instruction
* Use non-extended tags for saturating arithmetic, to keep it
simple so that all the arithmetic operations can be done the same
way.
- Sema: unify analyzeArithmetic with analyzeSatArithmetic
- implement comptime `+|`, `-|`, and `*|`
- allow float operands to saturating arithmetic
* `<<|` allows any integer type for the RHS.
* C backend: fix rebase conflicts
* LLVM backend: reduce the amount of branching for arithmetic ops
* zig.h: fix magic number not matching actual size of C integer types
