ziglang / www.ziglang.org Goto Github PK

You know, the equivalent for Python's pip (etc)

I'm trying to add new translation for www.ziglang.org, but I found the Get Started button is always lead me to the English version of the page.
I am not familiar with hugo, I don’t know how to implement language redirection..

Improving this will make them more consistent

I am totally new to zig and read your document on the language and found it helpful. It enabled me to make a start on learning the language. However I could not find any documentation on the functions in the zig standard library. I realise that I can read the code but when you have just read the language manual today, expecting one to read the code is a little bit much. Can somebody please work on providing some links to the main language reference manual to documentation on the entire standard library ? This would be enormously helpful and I think it would also help more people get interested in learning the language. I have just downloaded and installed version 0.3 of the zig language.

There are two places in the current redesign of the website where we want to show snippets of code that give an idea to the user of how it's like to program in Zig.

One of those places is Learn/Code Examples, while the other is the front page where we have a somewhat strict limit in terms of lines and columns of code. Those limits can be slightly bent, but the general problem of finding a meaningful and succinct example remains.

Please share a few code examples that you think would be nice and for each also provide a couple of lines that describe what the code is showing (e.g. "A simple generic singly-linked list implementation").

If you want to submit a sample for the front page, please stay under 30 lines and 50 columns. Also please make it relevant to the arguments present on the frontpage about simplicity, comptime and performance+safety.

Also see #78 for more discussion on the website redesign.

Inspired by https://github.com/edent/SuperTinyIcons, I made a hand-written SVG of the Zig logo that is ~600 bytes. This should make it suitable for embedding in the language reference documentation, etc. Using an SVG optimizer, pushes it down to ~500 bytes, but it's not easy to tweak in that form. For comparison, the current logo is ~3.8 KB.

While it's not a pixel-perfect recreation of the original logo, it is intended to look the same at a cursory glance. Changes:

• Omitted text since it can be replaced with markup.
• Slightly reduced the aspect ratio to 3:2.

If there is interest in using this logo, I will start a PR that incorporates it into the website and documentation.

Current logo (rasterized):

Tiny logo (rasterized):

SVG source: https://gist.github.com/jayschwa/1ef7b11ae2e82e78d3ac434140113a2d

Consider moving the "index" sections on your website to the side.

• This prevents users from having to scroll down to get to some content, or back up again to look at the index.
• It's 2019 and most users have a monitor with a width of more than 1024 pixels, so maybe make some more use of that horizontal screen real estate.
• Other language docs like Rust also have their index/navigation moved to the side.

Of course, of all the pages of the website, the old article about Zig vs other language is the one that got to the front page of hacker news. And like one day after merging the first round of translations.

HN link: https://news.ycombinator.com/item?id=25797025

This made Andrew fix the page on the fly but now the existing tranlsations are out of sync. This is a diff of the changes:

7977181...25d9cd6

Pinging @codehz and @kassane. Sorry to ask again this early, but would you mind reflecting those changes in your translations?

Thanks!

Here it says:

My plan is to do a 0.7.1 bug fix release in 1-3 weeks

But here it says:

It is unlikely there will be a 0.7.1, however it is planned there will be a 0.8.1.

I'm trying to do some very simple formatted output to stdout.

The equivalent in C of what I'm trying to do is:

int n = 42;
printf("n = %d\n", n);

I know from the examples that I can do:

var n: i32 = 42;
std.debug.warn("n = {}\n", n);

but that writes to stderr, not to stdout. Or I can do (after some setup):

stdout_file.write("Hello, world!\n");

but that doesn't permit formatting.

I've been looking over the documentation (which says "Usually you don't want to write to stdout. You want to write to stderr.") and the runtime library sources. I could probably copy-and-paste the implementation of warn from the standard library and hack it to write to stdout rather than stderr, but that's not a satisfying solution.

which it does not per b6e09dd which overwrote the 0.7.0 section to add the 0.7.1 content. thankfully, it was not also removed from index.json

There is a link to http://connectfree.co.jp/ziglang but this page does not contain any information.

i just copied the hello world example,
i got the error:

zig build-exe hello.zig
./hello.zig:4:14: error: container 'std.debug' has no member called 'print'
std.debug.print("Hello, world!\n", .{});
^

I've been working for the last few weeks on a redesign of the website. I haven't changed the general graphical theme, but I've expanded the number of pages and restructured the front page drastically.

The work is being done in the hugo-redesign branch and unfortunately at the moment is a bit hard to get it working on your machine as it depends on the docgen tool. I'm working on a simplified version of it, but it's not ready yet. In the meantime you can preview the website here: http://ziglang.github.io/www.ziglang.org/

The main (but not sole) goal of this redesign is to make the site more accessible for the average developer who might not appreciate the in-depth overview of Zig that's currently present on the front page.

For this reason the in-depth overview has been moved inside the learning section, while the frontpage acts as a more general introduction to the Zig project as a whole, starting from the language itself, to the community and the Zig Software Foundation.

The main type of feedback I'm looking for at the moment is about the copy (i.e. the text), especially when it's small fixes that improve the wording or in general provide a more effective way of expressing what the text was trying to say in the first place. If you think something needs big changes, please provide adequate explanations and consider the impact on the surrounding text. For example, changing the "Performance and Safety" point with something else, will probably require to rethink the other two points as well.

Please try to keep the discussion focused on actionable points, if you want to have a general discussion and / or ask questions about what I'm trying to achieve with the website, please do so on Reddit: https://old.reddit.com/r/Zig/comments/jtjmq5/ziglangorg_redesign/

The front page of the website has not been updated to show a link to the Zig 0.6.0 release notes.

In the struct example:

fn setYBasedOnX(x: *f32, y: f32) void {
    const point = @fieldParentPtr(Point, "x", x);
    point.y = y;
}

is it supposed to be point.y = x;?

Contrast https://www.google.com/search?&q=oop+in+rust
and https://www.google.com/search?&q=oop+in+zip.

This site needs a page/section that says "no OOP support yet" IMO

It looks like the following link redirects to some spam-like, tracker website and the actual endpoint doesn't exist anymore.

2019-02-11 - Moving to Zig for ARM Development

I've been looking for the RSS feed of zig updates for quite some time now and I cannot seem to find it. Subscribing to RSS for me is way more convenient than fetching the json file as it integrates better with aggregators. I therefore propose to:

• add a file complying with the RSS protocol to the website
• add changelog to said feed

Zig version: 0.6.0+53c63bdb7 on Linux 5.8.14-arch1-1

https://ziglang.org/documentation/master/#ReleaseFast

Looks like --release-fast --release-safe --release-small were options in the past, but now they are replaced with -O [mode] where [mode] is Debug | ReleaseFast | ReleaseSafe | ReleaseSmall. Although I haven't found since which version they were replaced (if they were).

$ zig test --help
  ...
  -O [mode]                 Choose what to optimize for
    Debug                   (default) Optimizations off, safety on
    ReleaseFast             Optimizations on, safety off
    ReleaseSafe             Optimizations on, safety on
    ReleaseSmall            Optimize for small binary, safety off
  ...

Example:
zig test main-testing.zig --release-fast returns error: unrecognized parameter: '--release-fast'
zig test main-testing.zig -O ReleaseFast seems to work as intended.

There is currently nothing about the standard library in the docs. Even though this might be a moving target, it would be helpful to have at least a list of different modules and what functionality they cover + an overview of very common library functions (the available allocators, string functions, IO) just so you can get up and running writing a test program to feel the language out without reading through the library files. Bonus points for having the entire standard library docs automatically generated from the source code.

It is a touted advantage of Zig that its stdlib "integrates with libc but does not depend on it." In the overview page on the section about the tier system, it is mentioned that:

Thus it is practical to write a pure Zig application with no dependency on libc.

However, this is only possible on Linux, because it is the only OS that provides a stable ABI guarantee such that Zig could implement syscalls without linking to libc. But macOS/x86_64 is listed as a Tier 1 target, even though Zig must link to libc to make syscalls on that platform, as is necessary for other BSDs as well.

There are a few clues to how it would be done, such as the declarations of built in functions. However, there isn't a good description of how this should be done like there is for generic data structures, and some of the semantics are unclear. In particular:

• What is the var type, and what are its semantics? (it is in many declarations, but I can't find any documentation about it)
• Does zig use duck typing? Or do I need to specify constraints somehow to use operators or members of a type
• Are there any best practices for defining generic functions?
• Can you define generic functions the same way you do with structs, by returning an anonymous function pointer?
• Can you use a function (ex. @typeof) to compute the return type or parameter type of a function?

The docs do not describe how arrays work with the rest of the memory handling, like how are they copied, how do you allocate them with an allocator, how do you copy a an array allocated with the stack allocator to use another allocator etc

https://www.ziglang.org/ 😯

It is touted advantage of Zig that it "integrate with libc but does not depend on it." In the overview page on the section about the tier system, it is mentioned that:

Thus it is practical to write a pure Zig application with no dependency on libc.

However, this is only possible on Linux, because it is the only OS that provides a stable ABI guarantee such that Zig could implement syscalls without linking to libc. But macOS/x86_64 is listed as a Tier 1 target, even though Zig must link to libc to make syscalls on that platform.

On FF, I see the following. On Chrome, it seems OK.

This feature seems to exist but it's not mentioned in the docs.

else supports a capture group which probably just returns the value that was in the switch(...). parentheses.

const std = @import("std");
pub fn main() void {
    var b: i32 = 5;
    switch (b) {
        else => |x| std.debug.warn("{}\n", .{x}), // prints 5
    }
}

this is to remain consistent with the -Dtarget/-target ordering

I found that some examples were confusing. I'll explain why it's not clear and I'll suggest a solution at the end.

Error handling

https://github.com/ziglang/www.ziglang.org/blob/master/www/index.html#L725

This example is supposed to show that 'The switch keyword used on an error ensures that all
possible errors are handled'. Yet the output is an error: ... not handled. For someone not familiar with Zig, this is only marginally different from error discarded that is shown above. And the errors are literally not handled in this example which contradicts the sentence above.
It is also surprising to see an example on the official website that is not compiling.

Compile-time code execution

https://github.com/ziglang/www.ziglang.org/blob/master/www/index.html#L975

Because the example use zig test that compiles and executes the program immediately, the fact that the assert is executed at compile time is not made clear enough. The reader is supposed to either :

• make the difference between a compiler error and a stack trace (They look very similar.)
• or notice that the usual text displayed by the test harness is not present.

Suggestion

In these 2 examples, a sentence explaining why these errors were expected and what it is showing could be added. As I said a compiler error is not what is expected when running official examples.
Maybe these are obvious for programmers used to low-level, compiled languages (which I am not) but I think the introduction to a language should aim to be as easily understandable as possible.

Should that remain until varargs is gone from the newest release (probably 0.6.0 then) or just be deleted now so people can use the examples with master branch?

I know it supports variadic functions, since it is in several declarations. But it isn't clear how to use it, or what the type of the variadic argument is.

I am not sure what was meant to be written in the footer but this doesn't feel right.

When I try to compile the sine.zig example from https://ziglang.org/#Integration-with-C-libraries-without-FFIbindings using zig build-exe sine.zig -lsoundio -lc, I get the error message:

./sine.zig:27:1: error: extern functions have no body
extern fn write_callback(

The website does not scale properly on mobile devices. The HTML viewport meta tag should be used to set the viewport's width to the width of the device's screen and to set the correct initial zoom level when pages load:

<meta name="viewport" content="width=device-width, initial-scale=1.0">

Before adding the meta tag:

https://user-images.githubusercontent.com/33205782/77707044-4e878980-6fc4-11ea-94ae-dc2226f98bf3.jpg
https://user-images.githubusercontent.com/33205782/77707052-52b3a700-6fc4-11ea-9ea7-0ce77606d691.jpg

After adding the meta tag:

https://user-images.githubusercontent.com/33205782/77707031-4891a880-6fc4-11ea-9e23-f25cd0813446.jpg
https://user-images.githubusercontent.com/33205782/77707036-4b8c9900-6fc4-11ea-9bad-d1d6e07684da.jpg

However, with the current CSS, tables that are too broad are not clipped to fit into their padding box:

https://user-images.githubusercontent.com/33205782/77707042-4d565c80-6fc4-11ea-8d81-db73bde6917e.jpg

The following CSS code fixes this problem:

table {
    display: block;
    overflow: auto;
}

When a table overflows, it will be clipped to fit into its padding box and it will become scrollable:

https://user-images.githubusercontent.com/33205782/77707027-462f4e80-6fc4-11ea-951c-7acb9284ea14.jpg

There is no real information about how the allocators work.

They currently link to https://ziglang.org/#Tier-1-Support which I suppose should be https://ziglang.org/learn/overview/#Tier-1-Support.

The very first example does not compile, kind of. The problem is google takes you to the master doc while you have to use the one corresponding to the version installed (ziglang.org/documentation/0.5.0/ in my case).
I think that first semi-advanced Hello World with stdout manipulations should be removed completely - at this point the person reading it just wants to print "Hello, world!" in as little code as possible, and getting "error: type 'std.os.windows.GetStdHandleError!std.fs.file.File' does not support field access" on Hello World is not exactly reassuring

Anonymous functions (lambda functions) seem either to be missing for the docs or the language ;)

Issue moved from ziglang/zig#1550

Can we consider adding a "Are we game yet" and a "Are we Web yet" sections in our readme and site.

This is something that Rust does and helps the occasional lurkers to better gauge the current state of language.
eg.
https://www.arewewebyet.org/
http://arewegameyet.com/

It will also allow someone like me who is not following Zig development very closely, decide on the best time to try out the language seriously.

The Table of operators in the Zig 0.3.0 documentation shows the Address of operator as being &a.

The langref.html.in in the main repository looks correct as far as I can tell, so I'm not sure what's causing the & entity to be double escaped.

The homepage shows:

I found this is rendered due to the fact that 0.8.0 is not referenced in https://github.com/ziglang/www.ziglang.org/blob/master/config.toml#L11-L13

I am not sure if this is intentional or not, as I see the 0.8.0 release referred to as master in https://github.com/ziglang/www.ziglang.org/blob/master/data/releases.json#L2-L3

Not sure what's up here - but it's kind of strange.

Currently, the website is rather unwelcoming to newcomers. When you land on the homepage, there are no code examples that could demonstrate Zig's capabilities, and beginner-friendly resources other than the official documentation are sparse and not directly linked on the website.

Nim's homepage and Go's homepage come to mind as examples that could be used to improve Zig's homepage.

The document talks about payloads at some places. They seem to be the ruby/rust-esque pipe-delimited blocks but it is never really defined.

ziglang/zig#717

As a Go user who is interested in Zig, I came across this sentence on the homepage:

C++, D, and Go have throw/catch exceptions, so foo() might throw an exception, and prevent bar() from being called.

Go does not have exceptions. Quote from their blog:

The language's design and conventions encourage you to explicitly check for errors where they occur (as distinct from the convention in other languages of throwing exceptions and sometimes catching them).

Thus, I would suggest to remove Go from the list of examples.
✌️