Skip to content

Commit

Permalink
Replaced to surfer.json and formated
Browse files Browse the repository at this point in the history
  • Loading branch information
mauro-balades committed Jul 6, 2024
1 parent 7cfe4aa commit b36fd5e
Show file tree
Hide file tree
Showing 26 changed files with 89 additions and 114 deletions.
26 changes: 0 additions & 26 deletions .github/workflows/docs.yml

This file was deleted.

2 changes: 1 addition & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -108,7 +108,7 @@ testing/
site/

docs/public/
.gluon
.surfer

# Patch generation
.moz-central
4 changes: 2 additions & 2 deletions .npmignore
Original file line number Diff line number Diff line change
Expand Up @@ -8,12 +8,12 @@ site/
tests/

.prettierrc.json
gluon.json
surfer.json
tsconfig.json
yarn.lock
.eslintignore
.eslintrc.json
.gluon
.surfer
.vscode/
.github/
.eslintrc.js
Expand Down
6 changes: 3 additions & 3 deletions docs/config.toml
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
name = "Gluon"
description = "Build Firefox-based browsers with ease"
license = "MPL 2.0"
homepage = "https://github.com/pulse-browser/gluon"
homepage = "https://github.com/zen-browser/surfer"
min_version = "1.14.0"

# The URL the site will be built for
base_url = "https://docs.gluon.dev"
base_url = "https://docs.surfer.dev"

# Whether to automatically compile all Sass files in the sass directory
compile_sass = true
Expand All @@ -20,7 +20,7 @@ highlight_code = true

[extra]
logo = "https://raw.githubusercontent.com/microsoft/fluentui-emoji/main/assets/Package/3D/package_3d.png"
release = "https://api.github.com/repos/pulse-browser/gluon/releases/latest"
release = "https://api.github.com/repos/zen-browser/surfer/releases/latest"

[author]
name = "TrickyPR"
22 changes: 11 additions & 11 deletions docs/content/getting-started/fileStructure.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ Lets take a look at the file structure of your project. It should look something

```filesystem
├─ .gitignore
├─ gluon.json
├─ surfer.json
├─ configs
│ ├─ common
│ │ └─ mozconfig
Expand Down Expand Up @@ -44,24 +44,24 @@ Lets take a look at the file structure of your project. It should look something
│ └─ windows
│ ├─ browser-css.patch
│ └─ jar-mn.patch
├─ .gluon
├─ .surfer
│ └─ ...
└─ engine
└─ ...
```

Whilst this may seem large (especially if you look inside of the `engine`) directory, it is all fairly manageable.

## gluon.json
## surfer.json

The primary configuration file for your project is the `gluon.json` file. This is where you will put information about your browser so Gluon can build it correctly. It should look something like this:
The primary configuration file for your project is the `surfer.json` file. This is where you will put information about your browser so Gluon can build it correctly. It should look something like this:

```json
{
"name": "Gluon Example Browser",
"vendor": "Fushra",
"appId": "dev.gluon.example",
"binaryName": "gluon-example-browser",
"appId": "dev.surfer.example",
"binaryName": "surfer-example-browser",

"version": {
"product": "firefox",
Expand Down Expand Up @@ -109,9 +109,9 @@ This directory is also where you would put [branding assets for your browser](/g

## src/

The source folder contains all of the modifications that you have made to Firefox. These come in two types, inserted files (and folders) and patches. Both of these are applied using the `gluon import` command.
The source folder contains all of the modifications that you have made to Firefox. These come in two types, inserted files (and folders) and patches. Both of these are applied using the `surfer import` command.

Inserted files are just files (and folders) that you have inserted into the Firefox source code. These will overwrite existing files if they already exist. On Linux and MacOS, these are symlinked so when you change a file in `src/`, the change will be mirrored in Firefox's source code instantly. On Windows, you will need to run `gluon import` for these changes to apply.
Inserted files are just files (and folders) that you have inserted into the Firefox source code. These will overwrite existing files if they already exist. On Linux and MacOS, these are symlinked so when you change a file in `src/`, the change will be mirrored in Firefox's source code instantly. On Windows, you will need to run `surfer import` for these changes to apply.

Patches are changes to Firefox's files. As a rule of thumb, you should prefer splitting new content into a new file rather than using patches, but there are times when you must modify Firefox's source code. Each of these patch files are just git patch files:

Expand All @@ -131,15 +131,15 @@ index 404a88b218c652afac0cb2004676d22da53d48f3..5a4668ef2970dd773536907f51f3e7e7
skin/classic/browser/monitor-border.png
```

In this patch, you can see that I am adding a `*` to the start of a line. You generate these patches by modifying the file in the `engine/` directory and running `gluon export` to export your changes to the src directory. Be careful, if you do not export your changes, they will not be saved and will not work on other developers' computers or yours after an update!
In this patch, you can see that I am adding a `*` to the start of a line. You generate these patches by modifying the file in the `engine/` directory and running `surfer export` to export your changes to the src directory. Be careful, if you do not export your changes, they will not be saved and will not work on other developers' computers or yours after an update!

```sh
gluon export browser/themes/linux/jar.mn
surfer export browser/themes/linux/jar.mn
```

## engine/

The engine directory contains all of Firefox's source code. It is massive - around 15GB in size (around 11GB of that are build assets from when you run `gluon build`). I am not able to provide a full explanation of the contents of the directory.
The engine directory contains all of Firefox's source code. It is massive - around 15GB in size (around 11GB of that are build assets from when you run `surfer build`). I am not able to provide a full explanation of the contents of the directory.

However, most of the changes you will want to make will be in `engine/browser/`, which contains the source code for the browser's UI. Here are some of the important directories inside of the `engine/browser/` directory:

Expand Down
32 changes: 16 additions & 16 deletions docs/content/getting-started/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,15 +3,15 @@ title = "Setting up your project"
weight = 5
+++

## Getting started with gluon
## Getting started with surfer

### What is gluon
### What is surfer

Gluon is a build tool and documentation for creating firefox-based browsers. Its goal is to simplify the process of creating web browsers to encourage competition and development within the space.

### Getting help

If you are having problems with following these instructions, or with gluon in general, please contact us. You can [create a discussion on github](https://github.com/pulse-browser/gluon/discussions/new), ping @trickypr on the [Fushra Discord](https://discord.gg/xNkretH7sD).
If you are having problems with following these instructions, or with surfer in general, please contact us. You can [create a discussion on github](https://github.com/zen-browser/surfer/discussions/new), ping @trickypr on the [Fushra Discord](https://discord.gg/xNkretH7sD).

### System requirements

Expand All @@ -24,17 +24,17 @@ If you are having problems with following these instructions, or with gluon in g
The first thing you are going to need to do is to install Gluon. As it is a nodejs program it can be installed through npm or yarn.

```sh
npm install -g gluon-build@next
npm install -g surfer-build@next
# or
yarn global add gluon-build@next
yarn global add surfer-build@next

# Note: Linux and mac users may have to run the above command with sudo
```

Now create a git repo and clone it to your local machine. Then run the following:

```sh
gluon setup-project
surfer setup-project
```

This will ask you a variety of questions in relation to your project setup. Firstly, the release of the browser you want to bind to.
Expand All @@ -50,7 +50,7 @@ This will ask you a variety of questions in relation to your project setup. Firs

You can change what version you are bound to at any time. Pulse Browser currently uses the stable releases, but if you want a lower workload, the newer Extended Support releases might be good for you.

Then next is the version of the browser you want to use. By default gluon will populate this with the latest version available, which we recommend using. Simply click enter to accept.
Then next is the version of the browser you want to use. By default surfer will populate this with the latest version available, which we recommend using. Simply click enter to accept.

```
? Enter the version of this product › 102.0.1
Expand All @@ -65,7 +65,7 @@ Next it will ask for the name of your browser. Avoid references to Firefox or ot
The binary name is the name that your program will be run from. We recommend that you add `-browser` to the end to [avoid conflicts with common utilities](https://github.com/dothq/browser/issues/604).

```
? Enter the name of the binary › gluon-example-browser
? Enter the name of the binary › surfer-example-browser
```

Vendor is the company (or solo developer) who is creating the browser.
Expand All @@ -77,7 +77,7 @@ Vendor is the company (or solo developer) who is creating the browser.
The appid follows reverse dns naming conventions. For example, Fushra owns the domain `fushra.com`, so our browser is `com.fushra.browser.desktop`. If you do not have a domain, you can use your username / pseudonym as the appid, e.g. `trickypr.watermelon`.

```
? Enter an appid › dev.gluon.example
? Enter an appid › dev.surfer.example
```

Next you need to chose a starting template for your browser. If you know what you are doing, you can go with `None` and configure it how you like. Otherwise, we recommend you stick with `UserChrome`.
Expand All @@ -88,39 +88,39 @@ Next you need to chose a starting template for your browser. If you know what yo
❯ User Chrome (custom browser css, simplest)
```

Now you have created the directory structure for your project, you can build it for the first time. First, ask gluon to download the firefox source.
Now you have created the directory structure for your project, you can build it for the first time. First, ask surfer to download the firefox source.

```sh
gluon download
surfer download
```

If you are running this for the first time, you will need to install the firefox dependencies. You can do this via boostrapping:

```sh
gluon bootstrap
surfer bootstrap
```

After the source code has been downloaded, the changes to firefox described in the source code must be applied.

```sh
gluon import
surfer import
```

Finally, you can start building the firefox source code. This takes around an hour and a half on my computer, but the binary output will be cached, making later builds faster

```sh
gluon build
surfer build
```

Now you can finally start the browser!

```sh
gluon run
surfer run
```

## Common errors

Here are some common errors that you might run into whilst running `gluon build` and some potential fixes.
Here are some common errors that you might run into whilst running `surfer build` and some potential fixes.

### Anything to do with `wasm-ld`

Expand Down
8 changes: 4 additions & 4 deletions docs/content/guides/autoUpdates.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ Attached to your "brand", you will need to include information regarding that br
"release": {
"displayVersion": "1.0.0-a.17",
"github": {
"repo": "pulse-browser/browser"
"repo": "zen-browser/desktop"
},
"x86": {
"windowsMar": "windows.mar",
Expand All @@ -39,14 +39,14 @@ Attached to your "brand", you will need to include information regarding that br

The release key includes both the latest version (`displayVersion`) and release info. In this case, binaries are released to github. For `x86`, we provide a number of `.mar` files for each platform. `.mar` files are "Mozilla Archives" and are used to distribute updates.

When creating update manifests, they will point to [the release tagged `displayVersion`](https://github.com/pulse-browser/browser/releases/tag/1.0.0-a.17). The update manifests tell Mozilla's updater to download the update manifest with the version that corresponds with the file name above. So an x86 linux computer will download the `linux.mar` file and use that to update.
When creating update manifests, they will point to [the release tagged `displayVersion`](https://github.com/zen-browser/desktop/releases/tag/1.0.0-a.17). The update manifests tell Mozilla's updater to download the update manifest with the version that corresponds with the file name above. So an x86 linux computer will download the `linux.mar` file and use that to update.

## Creating MAR files and update manifests

Both `.mar` files and the update manifests are automatically created by running `gluon package`. This will generate a number of files in the `dist` directory.
Both `.mar` files and the update manifests are automatically created by running `surfer package`. This will generate a number of files in the `dist` directory.

An `output.mar` will be included in the root, which you should rename to the appropriate platform. For example, `linux.mar` for linux. This should be included with your GitHub release.

Update manifests are stored in the `dist/update` directory. The contents of this directory should be uploaded to a webserver (e.g. GitHub Pages or S3) such that their root is at `/updates/browser/`.

You will then need to set the `updateHostname` in `gluon.json` to the url of your update server. For Pulse, this is `updates.pulsebrowser.app`. You may also need to change the update server specified [here](https://searchfox.org/mozilla-central/rev/560b7b1b174ed36912b969eee0c1920f3c59bc56/build/moz.build#94).
You will then need to set the `updateHostname` in `surfer.json` to the url of your update server. For Pulse, this is `updates.pulsebrowser.app`. You may also need to change the update server specified [here](https://searchfox.org/mozilla-central/rev/560b7b1b174ed36912b969eee0c1920f3c59bc56/build/moz.build#94).
10 changes: 5 additions & 5 deletions docs/content/guides/branding.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ Before you ship your browser, you will want to include your own branding, rather

## Creating a brand

You will first need to add a `brands` key within your `gluon.json`. For example:
You will first need to add a `brands` key within your `surfer.json`. For example:

```json
{
Expand All @@ -30,18 +30,18 @@ More information regarding the available keys for this config object can be foun

You will then need to create the folder `config/branding/<brand_name>`. In here, you will need to add a high-resolution `logo.png` (which will then be downscaled on import) and a `MacOSInstaller.svg` file, which will be used as the background for the macOS dmg file.

When you add or change a brand, you will need to reimport your changes and specify the brand to target using `gluon set brand`.
When you add or change a brand, you will need to reimport your changes and specify the brand to target using `surfer set brand`.

## Specifying which brand to target

You can specify the brand that you want to build for using the `gluon set brand <brand_name>` command. For example:
You can specify the brand that you want to build for using the `surfer set brand <brand_name>` command. For example:

```sh
gluon set brand stable
surfer set brand stable
```

Note that once you have set a new brand, you will need to rebuild your browser for changes to take effect:

```sh
gluon build
surfer build
```
4 changes: 2 additions & 2 deletions docs/content/guides/includingAddons.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ weight = 10

# Including addons

Gluon provides an automated system for including extensions in your project. The addons are downloaded and included during the `download` build step. Addons can be included in the project config (`gluon.json`).
Gluon provides an automated system for including extensions in your project. The addons are downloaded and included during the `download` build step. Addons can be included in the project config (`surfer.json`).

```json
{
Expand Down Expand Up @@ -84,5 +84,5 @@ let navbarPlacements = [
Finally, export the changes you have made:

```sh
gluon export-file browser/components/customizableui/CustomizableUI.jsm
surfer export-file browser/components/customizableui/CustomizableUI.jsm
```
6 changes: 3 additions & 3 deletions docs/content/guides/removingPocket.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ weight = 5

# Removing pocket

**Note:** This expects you have gluon setup.
**Note:** This expects you have surfer setup.

## Disabling in firefox.js

Expand Down Expand Up @@ -42,7 +42,7 @@ user_pref(
Now you simply need to export the changes made to `firefox.js`:

```sh
gluon export-file browser/app/profile/firefox.js
surfer export-file browser/app/profile/firefox.js
```

## Removing pocket icon from toolbar
Expand Down Expand Up @@ -70,5 +70,5 @@ let navbarPlacements = [
Remove the `save-to-pocket-button` item from the array and export the changes:

```sh
gluon export-file browser/components/customizableui/CustomizableUI.jsm
surfer export-file browser/components/customizableui/CustomizableUI.jsm
```
Loading

0 comments on commit b36fd5e

Please sign in to comment.