Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/primecitizens/pcz

A reimagination of Go, using unmodified official toolchain
https://github.com/primecitizens/pcz

go golang std stdlib toolchain wasm webapp

Last synced: about 1 month ago
JSON representation

A reimagination of Go, using unmodified official toolchain

Awesome Lists containing this project

README 

        
# 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](https://go.dev/doc/install) 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"`)



  ```bash

  go install github.com/primecitizens/pcz

  ```



## Usage



Here are some [examples](./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`

- [x] `make`

  - [x] `slice`

  - [ ] `map`

  - [ ] `chan`

- [x] `new`

- [ ] `go`

- [ ] `defer`

  - [x] 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)`)

- [x] `clear`

- [x] `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](https://github.com/primecitizens/pcz/blob/master/ROADMAP.md) for more details).



## Contributing



Read [CONTRIBUTING.md](./CONTRIBUTING.md) for general guidelines.



Some elementary tasks:



- documentation

  - estimate the minimum brain power need to understand the design.

- find `TODO`s in the source code and implement.

  - start from [`ffi/js`](./std/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)](./LICENSE.chromium).



Code written by Prime Citizens is licensed under the [Apache-2.0 License](./LICENSE):



```txt

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.

```