ForgeZero/README at main · forgezero-cli/ForgeZero · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
ForgeZero

DOCUMENTATION: https://forgezero-cli.github.io/forgezero-docs/

=========

ForgeZero is a zero-overhead build tool for assembly, C, C++, Objective-C,
and Gloria. It wraps NASM, GAS, FASM, GCC, Clang, Zig, and LD behind a
single command-line interface, and provides fast, allocation-free builds
without Makefiles or configuration.

-----------
Project Philosophy

This tool isn’t here to hide the compiler from you.
It’s built for people who know what a linker actually does, and aren’t afraid to tell it what to do.
You pay for speed with knowledge — of flags, of libraries, of architectures.
Zero magic. Maximum performance.
If you want a black box, go use something else.
If you want to control the box — welcome.

Quick Start
-----------

* Report a bug: https://github.com/forgezero-cli/ForgeZero/issues
* Get the latest release: https://github.com/forgezero-cli/ForgeZero
* Build ForgeZero: See INSTALL
* Build your project with fz: See QUICKSTART

Essential Documentation
------------------------

All users should be familiar with:

* Build modes & languages: LANGUAGES
* CLI reference: CLI-REFERENCE
* Configuration file: TOML_CONFIG
* License: See LICENSE

Full documentation index: INDEX


Who Are You?
============

Find your role below:

* New User - Building a project with fz for the first time
* Assembly Developer - Writing NASM, GAS, or FASM sources
* C / C++ / Objective-C Developer - Building with GCC, Clang, or Zig
* Gloria Developer - Writing and compiling Gloria sources
* Security Auditor - SBOM generation and SAST review
* Release Engineer - Reproducible and verifiable builds
* Cross-Compilation / Embedded Engineer - Targeting non-host platforms
* WebAssembly Developer - Building WASM targets
* Contributor - Extending or fixing ForgeZero itself


For Specific Users
===================

New User
--------

Start here:

* Installation: INSTALL
* Quick Start & Usage: QUICKSTART
* Exit Codes & Troubleshooting: ERROR_HANDLING

Assembly Developer
-------------------

* Build Modes & Extensions: LANGUAGES
* Assembler Backends: SPECS
* CLI Build Reference: CLI-REFERENCE

C / C++ / Objective-C Developer
---------------------------------

* Language Guide: LANGUAGES
* Build Modes & Extensions: LANGUAGES
* CLI Build Reference, Profiles & Linking: CLI-REFERENCE
* Zig Backend: SPECS

Gloria Developer
------------------

* Gloria Language: LANGUAGES
* Build Modes & Extensions: LANGUAGES

Security Auditor
------------------

* Supply Chain Security (SBOM + SAST): SECURITY
* Aegis Security Core: INTERNALS
* Virtual Filesystem Layer (Aegis): INTERNALS

Release Engineer
------------------

* Reproducible Builds, Verify, Bench: PERFORMANCE
* Supply Chain Security: SECURITY

Cross-Compilation / Embedded Engineer
----------------------------------------

* Cross-Compilation Targets: WORKFLOW
* Configuration File Reference: TOML_CONFIG

WebAssembly Developer
------------------------

* WASM & Web Targets: WORKFLOW

Contributor
-------------

* Project Tools (init, contribute, LSP, update): WORKFLOW
* Doctor, Platform Readiness, Testing Standards: INTERNALS
* HADES Engine, Contributing, License: INTERNALS
* Roadmap: ARCHITECTURE


Performance
===========

Measured against `nasm -f elf64 && ld` and `make -j4`, via hyperfine
(warmup 3, >= 10 runs). Test system: Intel Core i5-10310U (4C/8T,
1.7 GHz base), Arch Linux, NVMe SSD.

    modules     fz              make -j4          speedup
    -------     --------------  ----------------  -------
    20          19.3 +- 1.2 ms  45.4  +- 2.3  ms   2.35x
    50          31.1 +- 1.3 ms  85.0  +- 2.1  ms   2.73x
    100         57.0 +- 5.3 ms  185.5 +- 7.7  ms   3.25x
    150         73.1 +- 4.3 ms  229.3 +- 3.6  ms   3.14x
    200         82.2 +- 4.2 ms  291.1 +- 11.2 ms   3.54x
    400         223.1 +- 9.8 ms 1105.0 +- 24.1 ms  4.95x

Stress test, 5000 C files, AMD Ryzen 7 PRO 4750U (16 threads):

    ninja -j16    ~28.9 s
    fz            ~597 ms   (47.3x; 98% utilization across
                              16 threads; ~47 MB resident)

Full benchmark methodology and reproduction steps: PERFORMANCE


Communication and Support
==========================

* Issues: https://github.com/forgezero-cli/ForgeZero/issues
* Source: https://github.com/forgezero-cli/ForgeZero
* Author: alexvoste <https://github.com/alexvoste>
* License: GPLv3 - see LICENSE

You can find all the news about updates and announcements of upcoming versions rh: https://coderlegion.com/user/alexvoste