README.md

pcz

Warning This project is in its 'move fast and break things' stage, everything is EXPERIMENTAL.

A reimagination of Go, using unmodified official toolchain (currently go1.21).

Goals

• Be FFI friendly: unless it's a kernel, all useful programs work with FFI heavily.
• Work natively
  • Adapt to the running enviornment rather than insisting an opinionated way.
  • Provide platform native APIs: managing platform SDKs really sucks, do no more!
• Expand* adoption of Go to...
  • Web/Nodejs applications.
  • Cross-platform GUI with native experience (native GUI widgets).
  • Low-level system programming (think crun, systemd), EFI applications.
  • Kernel and Firmware.

*There are already impressive achievements made in these areas using official std.

Non-Goals

• Change the way the Go team works or make them change their decisions.

Components

• std: A custom Go standard library and runtime.

• pcz: A tool to build applications using custom std.

  • pcz build works like go build (invoking go tool compile/asm/link/pack) but with different options.
  • pcz dev provides easy development enironment setup.

• h2y: A library to flatten AST.

  • generate API specifications from C/Objective-C header files and WebIDL files (using llvm and webidl2.js).

• ffigen: A library to create go packages from specifications generated by h2y.

NOTE We will open source h2y and ffigen after all platform sdks are added and the project itself gained enough popularity.

Installation

1. Install go1.21 toolchain to your working machine

   • If you don't have any go toolchain installed, please refer to the official Go installation doc for guidance.
   • Otherwise, you can download and install it by running go install golang.org/dl/go1.21.2@latest and "$(go env GOPATH)/bin/go1.21.2" install, then it's available as "$(go env GOPATH)/bin/go1.21.2".

2. Install pcz from source code like most cli tools written in Go. (After running the command below, you may find the pcz at "$(go env GOPATH)/bin/pcz")

go install github.com/primecitizens/pcz

Usage

Here are some examples for your reference.

In General:

• Use github.com/primecitizens/pcz/std as your stdlib, and make sure your application doesn't use packages from the official std.
  • Some of the packages may work, but due to the lacking of GC, there can be memory leaks in you application.
• Run pcz with go1.21 toolchain, no other version of go toolchain is supported for now.
  • You can ensure this by setting the environment variable GOROOT to the path to the toolchain home (if pcz wasn't built with local go1.21 toolchain).
• Import the runtime package explicitly (import _ github.com/primecitizens/pcz/std/runtime) in your application (usually inside the main package).
  • This is because pcz build doesn't implicitly include a runtime for you.

NOTE The std module is meant to be compatible with the go toolchain by using pcz (not the go command).

Go Language Support

• append
• make
  • slice
  • map
  • chan
• new
• go
• defer
  • inlined defer
  • runtime.deferproc(deferFn)
• panic
  • stacktrace
  • recover
• map
  • access (val, ok := m[key])
  • assign (m[key] = val)
  • delete (delete(m, key))
• chan
  • send (chan <- x)
  • receive (x, ok := <- chan)
  • close
• select
  • block (select {})
  • blocking (without default branch)
  • non-blocking (with default branch)
• type switch (switch x.(type))
• type assertions (y, ok := x.(T))
• clear
• min, max (compiler intrinsic)

NOTE When using make and new, memory will be allocated using the default allocator of the current goroutine, which can be obtained by calling thread.G().G().DefaultAlloc().

Currently our major focus is on providing support for platfrom natvie apis, thus most Go language features except those doesn't require runtime support are missing, this is mainly because most runtime features require allocation and scheduling, thus depends on platform apis we are working on (see ROADMAP.md for more details).

Contributing

Read CONTRIBUTING.md for general guidelines.

Some elementary tasks:

• documentation
  • estimate the minimum brain power need to understand the design.
• find TODOs in the source code and implement.
  • start from ffi/js can be a good choice.
• create meaningful examples.

Some intermediate tasks:

• parallel package build.
• port libraries from the official std with careful redesign.
  • reimplement protocols with the new encoding/binary
  • minimum allocation.
• implement math/matrix package

Some hard tasks:

• (UI) design and implement a constraint-layout resolver.
  • for web apps, it will replace the CSS box model (as we are going avoid using html attributes as much as possible (e.g. id, name)).
  • for native platforms, it will be used to layout native widgets.
• (sched) design a framework for writing scheduler
• (gc) design a framework for writing garbage collectors based on the write barrier generated by Go toolchain.

Credits

This project won't be possible without the excellent work done by the Go team, if it was not the Go programming language, we could never find love in programming, let alone this project.

We would also like to thank everyone adopting Go to make programming in general more accessible to laypeople/peasants like us, your splendid resources really helped us to improve our understandings and skills.

LICENSE

WebIDL files copied from the Chromium project are licensed under its BSD 3-Clause License (LICENSE.chromium).

Code written by Prime Citizens is licensed under the Apache-2.0 License:

Copyright 2023 The Prime Citizens

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.