initialize base structureHEADmaster

6 files changed, 591 insertions, 1 deletions

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..ecbfd59
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,4 @@
+/build/
+/src/
+/result
+/result-*
diff --git a/.justfile b/.justfile
new file mode 100644
index 0000000..188e852
--- /dev/null
+++ b/.justfile
@@ -0,0 +1,35 @@
+src := "src/main.c3"
+bin := "build/csh"
+
+default:
+    @just --list
+
+tangle:
+    emacs -Q --batch --eval "(require 'org)" --eval '(org-babel-tangle-file "README.org")'
+
+run: tangle _prep
+    c3c compile-run {{src}} -o {{bin}}
+
+build: tangle _prep
+    c3c compile {{src}} -O0 -g -o {{bin}}
+
+release: tangle _prep
+    c3c compile {{src}} -O5 -o {{bin}}
+
+asan: tangle _prep
+    c3c compile-run {{src}} -O0 -g --sanitize=address -o {{bin}}
+
+tsan: tangle _prep
+    c3c compile-run {{src}} -O0 -g --sanitize=thread -o {{bin}}
+
+example name: tangle _prep
+    c3c compile-run src/{{name}}.c3 -o build/{{name}}
+
+valgrind: build
+    valgrind --leak-check=full --error-exitcode=1 ./{{bin}}
+
+clean:
+    rm -rf build src
+
+_prep:
+    @mkdir -p build
diff --git a/README.org b/README.org
index 5f602ba..bd6c473 100644
--- a/README.org
+++ b/README.org
@@ -1 +1,263 @@
-#+title: README
+#+title: csh
+#+author: cashmere
+#+property: header-args:c3 :mkdirp yes :comments no
+
+* Overview
+
+A C3 playground. =c3c= compiles source files directly, with no =project.json=. =just= drives the builds, =shell.nix= pins the toolchain through =npins=. The code blocks in this file tangle to =src/= with =org-babel-tangle=.
+
+* Quick start
+
+#+begin_src sh
+nix-shell          # c3c, just, valgrind, pinned via npins
+just run           # tangle, then compile and run src/main.c3
+#+end_src
+
+* Layout
+
+#+begin_example
+.
+├── README.org       # source: prose and c3 blocks
+├── shell.nix        # toolchain: c3c, just, valgrind, pinned via npins
+├── npins/           # nixpkgs pin (same revision as the nixos config)
+├── .justfile        # tangle, build, run, sanitizer targets
+├── src/             # tangled c3 (generated, gitignored)
+└── build/           # output binaries (gitignored)
+#+end_example
+
+* Targets
+
+| Recipe         | What it does                                             |
+|----------------+----------------------------------------------------------|
+| just tangle    | regenerate src/*.c3 from this README                     |
+| just run       | tangle, then compile and run src/main.c3                 |
+| just build     | safe debug build (-O0 -g, bounds, null, overflow checks) |
+| just release   | -O5, all checks off, no backtrace                        |
+| just asan      | run under AddressSanitizer (use-after-free, leaks, OOB)  |
+| just tsan      | run under ThreadSanitizer (data races)                   |
+| just example X | compile and run a named example, e.g. just example tcp   |
+| just valgrind  | build, then run under valgrind                           |
+| just clean     | remove build/ and the generated src/                     |
+
+* The program
+
+=src/main.c3= covers iteration and error handling.
+
+Module and imports:
+
+#+begin_src c3 :tangle src/main.c3
+module csh;
+
+import std::io;
+#+end_src
+
+** foreach and ranges
+
+=foreach= gives the index first, the value second. =&= binds the value by reference, =foreach_r= iterates backwards. There is no numeric range loop, so a macro with a trailing =@body= block adds one:
+
+#+begin_src c3 :tangle src/main.c3
+macro @range(usz start, usz end; @body(i)) {
+    for (usz i = start; i < end; i++) @body(i);
+}
+
+macro @step(usz start, usz end, usz by; @body(i)) {
+    for (usz i = start; i < end; i += by) @body(i);
+}
+#+end_src
+
+Packaged as a =.c3l= library, helpers like these carry across projects.
+
+** Errors
+
+Each function returns an Optional (=T?=) and propagates failure with =!=. A single handler at the top sinks it. =~= turns a fault into an Optional, =??= supplies a default.
+
+#+begin_src c3 :tangle src/main.c3
+faultdef BAD_PORT;
+
+fn int? parse_port(String s) {
+    int port = s.to_int()!;
+    if (port < 1 || port > 65535) return BAD_PORT~;
+    return port;
+}
+#+end_src
+
+=tour= propagates, it never inspects an error itself:
+
+#+begin_src c3 :tangle src/main.c3
+fn void? tour() {
+    String[] protocols = { "irc", "ssh", "tcp" };
+    foreach (i, p : protocols) io::printfn("%d: %s", i, p);
+
+    @range(0, 3; usz n) io::printfn("range %d", n);
+    @step(0, 10, 2; usz n) io::printfn("step %d", n);
+
+    int port = parse_port("6667")!;
+    io::printfn("port %d ok", port);
+}
+#+end_src
+
+=main= is the single sink. Replace =6667= with =99999= or =nope= to take the failure path:
+
+#+begin_src c3 :tangle src/main.c3
+fn int main() {
+    if (catch err = tour()) {
+        io::eprintfn("error: %s", err);
+        return 1;
+    }
+    return 0;
+}
+#+end_src
+
+* Iterating your own types
+
+=foreach= works on any type implementing =@operator(len)= and =@operator([])=. Add =@operator(&[])= for =foreach (&x : ...)=.
+
+#+begin_src c3 :tangle src/iter.c3
+module csh::iter;
+
+import std::io;
+
+struct Ring {
+    int[4] data;
+}
+
+fn usz Ring.len(&self) @operator(len) => 4;
+fn int Ring.get(&self, usz i) @operator([]) => self.data[i];
+
+fn void main() {
+    Ring r = { { 10, 20, 30, 40 } };
+    foreach (i, v : r) io::printfn("ring[%d] = %d", i, v);
+
+    int[3] xs = { 1, 2, 3 };
+    foreach (&x : xs) *x *= 10;
+    foreach_r (x : xs) io::printfn("rev %d", x);
+}
+#+end_src
+
+* Collections
+
+Generic, allocator explicit, freed with =defer=. Pass =mem= for the heap or =tmem= for the temp arena.
+
+#+begin_src c3 :tangle src/store.c3
+module csh::store;
+
+import std::io;
+import std::collections::list;
+import std::collections::map;
+
+fn void main() {
+    List{String} names;
+    names.init(mem);
+    defer names.free();
+    names.push("cashmere");
+    names.push("tsoding");
+    foreach (n : names) io::printfn("name: %s", n);
+
+    HashMap{String, int} ages;
+    ages.init(mem);
+    defer ages.free();
+    ages["cashmere"] = 27;
+    io::printfn("age: %d", ages["cashmere"]!!);
+}
+#+end_src
+
+* Crypto and random
+
+=std::math::random= covers PRNGs, =std::hash::sha256= covers digests. Both ship in the standard library.
+
+#+begin_src c3 :tangle src/digest.c3
+module csh::digest;
+
+import std::io;
+import std::hash::sha256;
+import std::math::random;
+
+fn void main() {
+    int roll = random::rand(6) + 1;
+    io::printfn("dice: %d", roll);
+
+    char[32] sum = sha256::hash("cashmere");
+    io::print("sha256(cashmere) = ");
+    foreach (b : sum) io::printf("%02x", b);
+    io::printn("");
+}
+#+end_src
+
+* Networking
+
+A one-shot TCP echo server on =std::net::tcp=. Client and server both live in the standard library. Run =just example tcp=, then talk to it with =nc 127.0.0.1 6667=. This is the skeleton for an IRC or telnet bot.
+
+#+begin_src c3 :tangle src/tcp.c3
+module csh::echo;
+
+import std::io;
+import std::net::tcp;
+
+fn void? serve() {
+    TcpServerSocket server = tcp::listen("127.0.0.1", 6667, 10)!;
+    io::printn("listening on 127.0.0.1:6667");
+
+    TcpSocket sock = tcp::accept(&server)!;
+    char[256] buf;
+    usz n = sock.read(&buf)!;
+    sock.write(buf[:n])!;
+    sock.close()!;
+}
+
+fn int main() {
+    if (catch err = serve()) {
+        io::eprintfn("error: %s", err);
+        return 1;
+    }
+    return 0;
+}
+#+end_src
+
+* Safety
+
+C3 does not check memory safety at compile time. Bugs are caught at runtime through sanitizers, and prevented through convention, the way curl stays correct: strict conventions and CI that runs every sanitizer.
+
+The sanitizers are LLVM backed and one flag away:
+
+#+begin_src sh
+c3c compile-run src/main.c3 --sanitize=address   # use-after-free, double-free, OOB, leaks
+c3c compile-run src/main.c3 --sanitize=thread    # data races
+c3c compile-run src/main.c3 --sanitize=memory    # reads of uninitialised memory
+#+end_src
+
+AddressSanitizer includes LeakSanitizer, so =just asan= covers both use-after-free and leaks. =--safe=yes= (the default at =-O0= and =-O1=) adds bounds, null, overflow and contract checks.
+
+Develop in safe mode. Gate CI on =just asan= and =just tsan=. Keep =tmem= and =@pool= allocations inside their scope, and pair every =mem= allocation with =defer free()=.
+
+* Standard library
+
+C3 ships these:
+
+| Need        | Module                                                          |
+|-------------+-----------------------------------------------------------------|
+| random      | std::math::random (PCG, Xoshiro), std::crypto::entropy (CSPRNG) |
+| crypto      | std::crypto (AES, ChaCha20, Ed25519, Argon2, Keccak)            |
+| hashing     | std::hash (sha256, sha512, blake3, hmac, siphash, crc32)        |
+| tcp/udp     | std::net::tcp, std::net::udp (client and server, blocking)      |
+| json/base64 | std::encoding                                                   |
+| collections | std::collections (list, hashmap, deque, channels)               |
+| threads     | std::threads (pools and channels)                               |
+
+No HTTP and no TLS ship in std. For those, bind a C library.
+
+* C interop
+
+C3 is ABI compatible with C. Bind a library with =extern fn= declarations and a =-l= link flag.
+
+#+begin_src c3
+extern fn void puts(char*);
+extern fn void init_window(int w, int h, char* t) @extern("InitWindow");
+#+end_src
+
+#+begin_src sh
+c3c compile-run src/main.c3 -l raylib -l m -l dl -l pthread -l GL -l X11
+#+end_src
+
+* Notes
+
+Targets =c3c= 0.8.x. C3 is pre-1.0, so fault and Optional syntax shifts between releases. If a block stops compiling, check it against the docs for the pinned version.
diff --git a/npins/default.nix b/npins/default.nix
new file mode 100644
index 0000000..8ec5eca
--- /dev/null
+++ b/npins/default.nix
@@ -0,0 +1,260 @@
+/*
+  This file is provided under the MIT licence:
+
+  Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+  The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+*/
+# Generated by npins. Do not modify; will be overwritten regularly
+let
+  # Backwards-compatibly make something that previously didn't take any arguments take some
+  # The function must return an attrset, and will unfortunately be eagerly evaluated
+  # Same thing, but it catches eval errors on the default argument so that one may still call it with other arguments
+  mkFunctor =
+    fn:
+    let
+      e = builtins.tryEval (fn { });
+    in
+    (if e.success then e.value else { error = fn { }; }) // { __functor = _self: fn; };
+
+  # https://github.com/NixOS/nixpkgs/blob/0258808f5744ca980b9a1f24fe0b1e6f0fecee9c/lib/lists.nix#L295
+  range =
+    first: last: if first > last then [ ] else builtins.genList (n: first + n) (last - first + 1);
+
+  # https://github.com/NixOS/nixpkgs/blob/0258808f5744ca980b9a1f24fe0b1e6f0fecee9c/lib/strings.nix#L257
+  stringToCharacters = s: map (p: builtins.substring p 1 s) (range 0 (builtins.stringLength s - 1));
+
+  # https://github.com/NixOS/nixpkgs/blob/0258808f5744ca980b9a1f24fe0b1e6f0fecee9c/lib/strings.nix#L269
+  stringAsChars = f: s: concatStrings (map f (stringToCharacters s));
+  concatStrings = builtins.concatStringsSep "";
+
+  # If the environment variable NPINS_OVERRIDE_${name} is set, then use
+  # the path directly as opposed to the fetched source.
+  # (Taken from Niv for compatibility)
+  mayOverride =
+    name: path:
+    let
+      envVarName = "NPINS_OVERRIDE_${saneName}";
+      saneName = stringAsChars (c: if (builtins.match "[a-zA-Z0-9]" c) == null then "_" else c) name;
+      ersatz = builtins.getEnv envVarName;
+    in
+    if ersatz == "" then
+      path
+    else
+      # this turns the string into an actual Nix path (for both absolute and
+      # relative paths)
+      builtins.trace "Overriding path of \"${name}\" with \"${ersatz}\" due to set \"${envVarName}\"" (
+        if builtins.substring 0 1 ersatz == "/" then
+          /. + ersatz
+        else
+          /. + builtins.getEnv "PWD" + "/${ersatz}"
+      );
+
+  mkSource =
+    name: spec:
+    {
+      pkgs ? null,
+    }:
+    assert spec ? type;
+    let
+      # Unify across builtin and pkgs fetchers.
+      # `fetchGit` requires a wrapper because of slight API differences.
+      fetchers =
+        if pkgs == null then
+          {
+            inherit (builtins) fetchTarball fetchurl;
+            # Frustratingly, due to flakes and `fetchTree`, `fetchGit`
+            # has a different signature than the other builtin
+            # fetchers
+            fetchGit = args: (builtins.fetchGit args).outPath;
+          }
+        else
+          {
+            fetchTarball =
+              {
+                url,
+                sha256,
+              }:
+              pkgs.fetchzip {
+                inherit url sha256;
+                extension = "tar";
+              };
+            inherit (pkgs) fetchurl;
+            fetchGit =
+              {
+                url,
+                submodules,
+                rev,
+                name,
+                narHash,
+              }:
+              pkgs.fetchgit {
+                inherit url rev name;
+                fetchSubmodules = submodules;
+                hash = narHash;
+              };
+          };
+
+      path =
+        if spec.type == "Git" then
+          mkGitSource fetchers spec
+        else if spec.type == "GitRelease" then
+          mkGitSource fetchers spec
+        else if spec.type == "PyPi" then
+          mkPyPiSource fetchers spec
+        else if spec.type == "Channel" then
+          mkChannelSource fetchers spec
+        else if spec.type == "Url" || spec.type == "MutableUrl" then
+          mkUrlSource fetchers spec
+        else if spec.type == "Container" then
+          mkContainerSource pkgs spec
+        else
+          builtins.throw "Unknown source type ${spec.type}";
+    in
+    spec // { outPath = mayOverride name path; };
+
+  mkGitSource =
+    {
+      fetchTarball,
+      fetchGit,
+      ...
+    }:
+    {
+      repository,
+      revision,
+      url ? null,
+      submodules,
+      hash,
+      ...
+    }:
+    assert repository ? type;
+    # At the moment, either it is a plain git repository (which has an url), or it is a GitHub/GitLab repository
+    # In the latter case, there we will always be an url to the tarball
+    if url != null && !submodules then
+      fetchTarball {
+        inherit url;
+        sha256 = hash;
+      }
+    else
+      let
+        url =
+          if repository.type == "Git" then
+            repository.url
+          else if repository.type == "GitHub" then
+            "https://github.com/${repository.owner}/${repository.repo}.git"
+          else if repository.type == "GitLab" then
+            "${repository.server}/${repository.repo_path}.git"
+          else if repository.type == "Forgejo" then
+            "${repository.server}/${repository.owner}/${repository.repo}.git"
+          else
+            throw "Unrecognized repository type ${repository.type}";
+        urlToName =
+          url: rev:
+          let
+            matched = builtins.match "^.*/([^/]*)(\\.git)?$" url;
+
+            short = builtins.substring 0 7 rev;
+
+            appendShort = if (builtins.match "[a-f0-9]*" rev) != null then "-${short}" else "";
+          in
+          "${if matched == null then "source" else builtins.head matched}${appendShort}";
+        name = urlToName url revision;
+      in
+      fetchGit {
+        rev = revision;
+        narHash = hash;
+
+        inherit name submodules url;
+      };
+
+  mkPyPiSource =
+    { fetchurl, ... }:
+    {
+      url,
+      hash,
+      ...
+    }:
+    fetchurl {
+      inherit url;
+      sha256 = hash;
+    };
+
+  mkChannelSource =
+    { fetchTarball, ... }:
+    {
+      url,
+      hash,
+      ...
+    }:
+    fetchTarball {
+      inherit url;
+      sha256 = hash;
+    };
+
+  mkUrlSource =
+    {
+      fetchTarball,
+      fetchurl,
+      ...
+    }:
+    {
+      url,
+      hash,
+      unpack,
+      ...
+    }:
+    (if unpack then fetchTarball else fetchurl) {
+      inherit url;
+      sha256 = hash;
+    };
+
+  mkContainerSource =
+    pkgs:
+    {
+      image_name,
+      image_tag,
+      image_digest,
+      hash,
+      ...
+    }@args:
+    if pkgs == null then
+      builtins.throw "container sources require passing in a Nixpkgs value: https://github.com/andir/npins/blob/master/README.md#using-the-nixpkgs-fetchers"
+    else
+      pkgs.dockerTools.pullImage (
+        {
+          imageName = image_name;
+          imageDigest = image_digest;
+          finalImageTag = image_tag;
+          hash = hash;
+        }
+        // (if args.arch or null != null then { arch = args.arch; } else { })
+      );
+
+in
+mkFunctor (
+  {
+    input ? ./sources.json,
+  }:
+  let
+    data =
+      if builtins.isPath input then
+        # while `readFile` will throw an error anyways if the path doesn't exist,
+        # we still need to check beforehand because *our* error can be caught but not the one from the builtin
+        # See: <https://git.lix.systems/lix-project/lix/issues/1098>
+        if builtins.pathExists input then
+          builtins.fromJSON (builtins.readFile input)
+        else
+          throw "Input path ${toString input} does not exist"
+      else if builtins.isAttrs input then
+        input
+      else
+        throw "Unsupported input type ${builtins.typeOf input}, must be a path or an attrset";
+    version = data.version;
+  in
+  if version == 8 then
+    builtins.mapAttrs (name: spec: mkFunctor (mkSource name spec)) data.pins
+  else
+    throw "Unsupported format version ${toString version} in sources.json. Try running `npins upgrade`"
+)
diff --git a/npins/sources.json b/npins/sources.json
new file mode 100644
index 0000000..7806157
--- /dev/null
+++ b/npins/sources.json
@@ -0,0 +1,18 @@
+{
+  "pins": {
+    "nixpkgs": {
+      "type": "Git",
+      "repository": {
+        "type": "GitHub",
+        "owner": "nixos",
+        "repo": "nixpkgs"
+      },
+      "branch": "nixos-unstable",
+      "submodules": false,
+      "revision": "331800de5053fcebacf6813adb5db9c9dca22a0c",
+      "url": "https://github.com/nixos/nixpkgs/archive/331800de5053fcebacf6813adb5db9c9dca22a0c.tar.gz",
+      "hash": "sha256-x5UQuRsH3MqI0U9afaXSNqzTPSeZlRLvFAav2Ux1pNw="
+    }
+  },
+  "version": 8
+}
diff --git a/shell.nix b/shell.nix
new file mode 100644
index 0000000..816905f
--- /dev/null
+++ b/shell.nix
@@ -0,0 +1,11 @@
+{
+  sources ? import ./npins,
+  pkgs ? import sources.nixpkgs { },
+}:
+pkgs.mkShell {
+  packages = [
+    pkgs.c3c
+    pkgs.just
+    pkgs.valgrind
+  ];
+}