2023-01-30 12:08:48 +03:00
< table align = "center" >
< tbody >
< tr >
< td >
< p > < / p >
< pre >
O O
\ /
O —— Cr —— O
/ \
O O< / pre >
< / td >
< td > < h1 > Carbonyl< / h1 > < / td >
< / tr >
< / tbody >
< / table >
2022-11-11 12:23:16 +03:00
2022-12-27 19:26:32 +03:00
Carbonyl is a Chromium based browser built to run in a terminal. [Read the blog post ](https://fathy.fr/carbonyl ).
2022-11-11 12:23:16 +03:00
2022-12-27 19:26:32 +03:00
It supports pretty much all Web APIs including WebGL, WebGPU, audio and video playback, animations, etc..
2022-11-17 02:36:54 +03:00
2023-01-28 17:03:06 +03:00
It's snappy, starts in less than a second, runs at 60 FPS, and idles at 0% CPU usage. It does not require a window server (i.e. works in a safe-mode console), and even runs through SSH.
2022-11-17 02:36:54 +03:00
2022-12-27 19:26:32 +03:00
Carbonyl originally started as [`html2svg` ](https://github.com/fathyb/html2svg ) and is now the runtime behind it.
2022-11-18 12:48:10 +03:00
2023-01-23 13:47:56 +03:00
## Usage
2023-02-09 12:43:26 +03:00
> Carbonyl on Linux without Docker requires the same dependencies as Chromium.
### Docker
2023-01-23 13:47:56 +03:00
```shell
$ docker run -ti fathyb/carbonyl https://youtube.com
```
2023-02-09 12:43:26 +03:00
### npm
```console
$ npm install --global carbonyl
$ carbonyl https://github.com
```
2023-02-05 01:02:06 +03:00
2023-02-09 12:43:26 +03:00
### Binaries
2023-02-05 01:02:06 +03:00
2023-02-09 13:51:25 +03:00
- [macOS amd64 ](https://github.com/fathyb/carbonyl/releases/download/v0.0.2/carbonyl.macos-amd64.zip )
- [macOS arm64 ](https://github.com/fathyb/carbonyl/releases/download/v0.0.2/carbonyl.macos-arm64.zip )
- [Linux amd64 ](https://github.com/fathyb/carbonyl/releases/download/v0.0.2/carbonyl.linux-amd64.zip )
- [Linux arm64 ](https://github.com/fathyb/carbonyl/releases/download/v0.0.2/carbonyl.linux-arm64.zip )
2023-02-05 01:02:06 +03:00
2023-01-20 14:22:51 +03:00
## Demo
< table >
< tbody >
< tr >
< td >
< video src = "https://user-images.githubusercontent.com/5746414/213682926-f1cc2de7-a38c-4125-9257-92faecfc7e24.mp4" >
< / td >
< td >
< video src = "https://user-images.githubusercontent.com/5746414/213682913-398d3d11-1af8-4ae6-a0cd-a7f878efd88b.mp4" >
< / td >
< / tr >
< tr >
2023-01-20 15:09:03 +03:00
< td colspan = "2" >
2023-01-20 14:22:51 +03:00
< video src = "https://user-images.githubusercontent.com/5746414/213682918-d6396a4f-ee23-431d-828e-4ad6a00e690e.mp4" >
< / td >
< / tr >
< / tbody >
< / table >
2022-11-18 12:48:10 +03:00
2023-02-06 14:34:48 +03:00
## Known issues
2022-11-18 12:48:10 +03:00
2023-02-09 12:43:26 +03:00
- Fullscreen mode not supported yet
2022-11-11 12:23:16 +03:00
2023-01-31 05:55:39 +03:00
## Comparisons
### Lynx
2023-02-05 01:02:06 +03:00
Lynx is the original terminal web browser, and the oldest one still maintained.
2023-01-31 05:55:39 +03:00
#### Pros
2023-02-09 12:43:26 +03:00
- When it understands a page, Lynx has the best layout, fully optimized for the terminal
2023-01-31 05:55:39 +03:00
#### Cons
> Some might sound like pluses, but Browsh and Carbonyl let you disable most of those if you'd like
2023-02-09 12:43:26 +03:00
- Does not support a lot of modern web standards
- Cannot run JavaScript/WebAssembly
- Cannot view or play media (audio, video, DOOM)
2023-01-31 05:55:39 +03:00
### Browsh
2023-02-05 01:02:06 +03:00
Browsh is the original "normal browser into a terminal" project. It starts Firefox in headless mode and connects to it through an automation protocol.
2023-01-31 05:55:39 +03:00
#### Pro
2023-02-09 12:43:26 +03:00
- It's easier to update the underlying browser: just update Firefox
- This makes development easier: just install Firefox and compile the Go code in a few seconds
- As of today, Browsh supports extensions while Carbonyl doesn't, although it's on our roadmap
2023-01-31 05:55:39 +03:00
#### Cons
2023-02-09 12:43:26 +03:00
- It runs slower and requires more resources than Carbonyl. 50x more CPU power is needed for the same content in average, that's because Carbonyl does not downscale or copy the window framebuffer, it natively renders to the terminal resolution.
- It uses custom stylesheets to fix the layout, which is less reliable than Carbonyl's changes to its HTML engine (Blink).
2023-01-31 05:55:39 +03:00
2023-02-01 16:07:52 +03:00
## Operating System Support
2023-02-05 01:02:06 +03:00
2023-02-01 16:07:52 +03:00
As far as tested, the operating systems under are supported:
2023-02-05 01:02:06 +03:00
2023-02-09 12:43:26 +03:00
- Linux (Debian, Ubuntu and Arch tested)
- MacOS
- Windows 11 and WSL
2023-02-05 01:02:06 +03:00
2023-02-05 12:30:08 +03:00
## Contributing
Carbonyl is split in two parts: the "core" which is built into a shared library (`libcarbonyl`), and the "runtime" which dynamically loads the core (`carbonyl` executable).
The core is written in Rust and takes a few seconds to build from scratch. The runtime is a modified version of the Chromium headless shell and takes more than an hour to build from scratch.
If you're just making changes to the Rust code, build `libcarbonyl` and replace it in a release version of Carbonyl.
### Core
```console
$ cargo build
```
### Runtime
2022-11-14 11:58:00 +03:00
2023-01-29 05:51:23 +03:00
Few notes:
2023-02-09 12:43:26 +03:00
- Building the runtime is almost the same as building Chromium with extra steps to patch and bundle the Rust library. Scripts in the `scripts/` directory are simple wrappers around `gn` , `ninja` , etc..
- Building Chromium for arm64 on Linux requires an amd64 processor
- Carbonyl is only tested on Linux and macOS, other platforms likely require code changes to Chromium
- Chromium is huge and takes a long time to build, making your computer mostly unresponsive. An 8-core CPU such as an M1 Max or an i9 9900k with 10 Gbps fiber takes around ~1 hour to fetch and build. It requires around 100 GB of disk space.
2023-01-29 05:51:23 +03:00
2023-02-05 12:30:08 +03:00
#### Fetch
2022-11-11 12:23:16 +03:00
2023-01-29 05:51:23 +03:00
> Fetch Chromium's code.
2022-12-27 19:26:32 +03:00
```console
2023-01-29 05:51:23 +03:00
$ ./scripts/gclient.sh sync
```
2023-02-05 12:30:08 +03:00
#### Apply patches
2023-01-29 05:51:23 +03:00
> Any changes made to Chromium will be reverted, make sure to save any changes you made.
```console
$ ./scripts/patches.sh apply
2022-12-27 19:26:32 +03:00
```
2022-11-17 23:10:03 +03:00
2023-02-05 12:30:08 +03:00
#### Configure
2022-11-17 23:10:03 +03:00
2023-01-29 05:51:23 +03:00
```console
$ ./scripts/gn.sh args out/Default
```
> `Default` is the target name, you can use multiple ones and pick any name you'd like, i.e.:
>
> ```console
> $ ./scripts/gn.sh args out/release
> $ ./scripts/gn.sh args out/debug
> # or if you'd like to build a multi-platform image
> $ ./scripts/gn.sh args out/arm64
> $ ./scripts/gn.sh args out/amd64
> ```
When prompted, enter the following arguments:
```gn
import("//carbonyl/src/browser/args.gn")
# uncomment this to build for arm64
# target_cpu="arm64"
# uncomment this to enable ccache
# cc_wrapper="env CCACHE_SLOPPINESS=time_macros ccache"
# uncomment this if you're building for macOS
# use_lld=false
# uncomment this for a release build
# is_debug=false
# symbol_level=0
```
2023-02-05 12:30:08 +03:00
#### Build binaries
2022-11-17 23:10:03 +03:00
2022-12-27 19:26:32 +03:00
```console
2023-01-29 05:51:23 +03:00
$ ./scripts/build.sh Default
2022-11-17 23:10:03 +03:00
```
2023-01-29 05:51:23 +03:00
This should produce the following outputs:
2023-02-09 12:43:26 +03:00
- `out/Default/headless_shell` : browser binary
- `out/Default/icudtl.dat`
- `out/Default/libEGL.so`
- `out/Default/libGLESv2.so`
- `out/Default/v8_context_snapshot.bin`
2023-01-29 05:51:23 +03:00
2023-02-05 12:30:08 +03:00
#### Build Docker image
2022-11-17 23:10:03 +03:00
2022-12-27 19:26:32 +03:00
```console
2023-01-29 05:51:23 +03:00
# Build arm64 Docker image using binaries from the Default target
2023-02-01 12:14:29 +03:00
$ ./scripts/docker-build.sh Default arm64
2023-01-29 05:51:23 +03:00
# Build amd64 Docker image using binaries from the Default target
2023-02-01 12:14:29 +03:00
$ ./scripts/docker-build.sh Default amd64
2023-01-29 05:51:23 +03:00
```
2023-02-05 12:30:08 +03:00
#### Run
2023-01-29 05:51:23 +03:00
```
$ ./scripts/run.sh Default https://wikipedia.org
2022-11-17 23:10:03 +03:00
```