Replaced to surfer.json and formated

This commit is contained in:
Mauro Balades 2024-07-06 21:24:05 +02:00
parent 7cfe4aa88d
commit b36fd5e768
26 changed files with 89 additions and 114 deletions

View file

@ -1,26 +0,0 @@
name: Build docs
on:
push:
branches:
- main
paths:
- 'docs/**'
- '.github/**'
workflow_dispatch:
jobs:
docs:
runs-on: ubuntu-latest
steps:
- name: Checkout 🛎️
uses: actions/checkout@v2.3.1
- name: Deploy docs
uses: shalzz/zola-deploy-action@v0.13.0
env:
# Target branch
PAGES_BRANCH: gh-pages
BUILD_DIR: docs/
# Provide personal access token
TOKEN: ${{ secrets.ROBOT_TOKEN }}

2
.gitignore vendored
View file

@ -108,7 +108,7 @@ testing/
site/
docs/public/
.gluon
.surfer
# Patch generation
.moz-central

View file

@ -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

View file

@ -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
@ -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"

View file

@ -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
@ -44,7 +44,7 @@ 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
└─ ...
@ -52,16 +52,16 @@ Lets take a look at the file structure of your project. It should look something
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",
@ -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:
@ -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:

View file

@ -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
@ -24,9 +24,9 @@ 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
```
@ -34,7 +34,7 @@ yarn global add gluon-build@next
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.
@ -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
@ -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.
@ -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`.
@ -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`

View file

@ -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",
@ -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).

View file

@ -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
{
@ -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
```

View file

@ -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
{
@ -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
```

View file

@ -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
@ -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
@ -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
```

View file

@ -1,11 +1,11 @@
+++
title = "`gluon.json` Reference"
title = "`surfer.json` Reference"
weight = 0
+++
# gluon.json Reference
# surfer.json Reference
This reference guide may get outdated. If you need to check something, you can read [the config interface type](https://github.com/pulse-browser/gluon/blob/main/src/utils/config.ts#L96).
This reference guide may get outdated. If you need to check something, you can read [the config interface type](https://github.com/zen-browser/surfer/blob/main/src/utils/config.ts#L96).
## name
@ -43,7 +43,7 @@ The name of the output binary.
```json
{
"binaryName": "pulse-browser"
"binaryName": "zen-browser"
}
```
@ -97,13 +97,13 @@ Example:
Commands that maybe used:
```sh
gluon license-check
gluon lc # Alias
surfer license-check
surfer lc # Alias
```
## version
Provides information to gluon about the product and version that Gluon is responsible for managing.
Provides information to surfer about the product and version that Gluon is responsible for managing.
Specification:
@ -153,7 +153,7 @@ When set to `true`, symbolic links will be enabled on Windows. From internal tes
## addons
An index for each addon. These will be downloaded and configured as part of the `download` step that gluon performs. You can download extensions from AMO, Github or any URL. Note that the furha-robot will only be able to provide update checking to AMO and Github Extensions.
An index for each addon. These will be downloaded and configured as part of the `download` step that surfer performs. You can download extensions from AMO, Github or any URL. Note that the furha-robot will only be able to provide update checking to AMO and Github Extensions.
Specification:
@ -210,8 +210,8 @@ Example:
Commands that use this:
```sh
gluon download
gluon updates-addons # Generates update manifests for addons
surfer download
surfer updates-addons # Generates update manifests for addons
```
## brands
@ -261,7 +261,7 @@ Example:
"release": {
"displayVersion": "1.0.0",
"github": {
"repo": "pulse-browser/browser"
"repo": "zen-browser/desktop"
},
"x86": {
"windowsMar": "windows.mar",
@ -278,7 +278,7 @@ Example:
"release": {
"displayVersion": "1.0.0-b.0",
"github": {
"repo": "pulse-browser/browser"
"repo": "zen-browser/desktop"
},
"x86": {
"windowsMar": "windows.mar",
@ -295,7 +295,7 @@ Example:
"release": {
"displayVersion": "1.0.0-a.16",
"github": {
"repo": "pulse-browser/browser"
"repo": "zen-browser/desktop"
},
"x86": {
"windowsMar": "windows.mar",
@ -311,8 +311,8 @@ Example:
Commands:
```sh
gluon build
gluon package
gluon updates-browser
gluon set brand <brand_name>
surfer build
surfer package
surfer updates-browser
surfer set brand <brand_name>
```

2
docs/static/CNAME vendored
View file

@ -1 +1 @@
docs.gluon.dev
docs.surfer.dev

View file

@ -1,6 +1,6 @@
{
"name": "@zen-browser/surfer",
"version": "1.0.1",
"version": "1.0.2",
"description": "Simplifying building firefox forks!",
"main": "index.js",
"bin": {

View file

@ -9,7 +9,7 @@ import { Cmd } from './types'
export const commands: Cmd[] = [
{
cmd: 'bootstrap',
description: 'Bootstrap the gluon app.',
description: 'Bootstrap the surfer app.',
requestController: async () =>
(await import('./commands/bootstrap')).bootstrap,
},
@ -17,7 +17,7 @@ export const commands: Cmd[] = [
cmd: 'build',
aliases: ['b'],
description:
'Build the gluon app. Specify the OS param for cross-platform builds.',
'Build the surfer app. Specify the OS param for cross-platform builds.',
options: [
{
arg: '--u, --ui',
@ -131,7 +131,7 @@ export const commands: Cmd[] = [
aliases: ['pack'],
description: 'Package the browser for distribution.',
requestController: async () =>
(await import('./commands/package')).gluonPackage,
(await import('./commands/package')).surferPackage,
},
{
cmd: 'reset',
@ -146,7 +146,7 @@ export const commands: Cmd[] = [
},
{
cmd: 'setup-project',
description: 'Sets up a gluon project for the first time',
description: 'Sets up a surfer project for the first time',
requestController: async () =>
(await import('./commands/setup-project')).setupProject,
},

View file

@ -50,8 +50,8 @@ const applyConfig = async (os: string) => {
name: config.name,
vendor: config.name,
appId: config.appId,
brandingDir: existsSync(join(ENGINE_DIR, 'branding', 'gluon'))
? 'branding/gluon'
brandingDir: existsSync(join(ENGINE_DIR, 'branding', 'surfer'))
? 'branding/surfer'
: 'branding/unofficial',
binName: config.binaryName,
changeset,

View file

@ -60,7 +60,7 @@ export async function resolveAddonDownloadUrl(
`https://api.github.com/repos/${addon.repo}/releases/tags/${addon.version}`,
{
headers: {
'User-Agent': 'gluon-build -> addon downloader',
'User-Agent': 'surfer-build -> addon downloader',
},
}
)

View file

@ -18,7 +18,7 @@ import { generateBrowserUpdateFiles } from './updates/browser'
const machPath = resolve(ENGINE_DIR, 'mach')
export const gluonPackage = async () => {
export const surferPackage = async () => {
const brandingKey = dynamicConfig.get('brand') as string
const brandingDetails = config.brands[brandingKey]

View file

@ -105,7 +105,7 @@ async function importInternalPatch(): Promise<Task> {
}))
return patchMethod<gitPatch.IGitPatch>(
'gluon',
'surfer',
structuredPatches,
async (patch) => await gitPatch.apply(patch.path)
)

View file

@ -158,7 +158,7 @@ export async function setupProject(): Promise<void> {
}
gitignoreContents +=
'\n.dotbuild/\n.gluon/\nengine/\nfirefox-*/\nnode_modules/\n'
'\n.dotbuild/\n.surfer/\nengine/\nfirefox-*/\nnode_modules/\n'
writeFileSync(gitignore, gitignoreContents)
@ -166,7 +166,7 @@ export async function setupProject(): Promise<void> {
'Project setup complete!',
'',
`You can start downloading the Firefox source code by running |${BIN_NAME} download|`,
'Or you can follow the getting started guide at https://docs.gluon.dev/getting-started/overview/'
'Or you can follow the getting started guide at https://docs.surfer.dev/getting-started/overview/'
)
} catch (error) {
log.error(error)

View file

@ -6,7 +6,7 @@ import { existsSync, mkdirSync, readdirSync } from 'node:fs'
import { resolve } from 'node:path'
import { log } from '../log'
export const BIN_NAME = 'gluon'
export const BIN_NAME = 'surfer'
export const BUILD_TARGETS = ['linux', 'windows', 'macos']
export const ARCHITECTURE = ['i686', 'x86_64']
@ -28,7 +28,7 @@ export const PATCHES_DIR = resolve(
)
export const COMMON_DIR = resolve(process.cwd(), 'common')
export const CONFIGS_DIR = resolve(process.cwd(), 'configs')
export const MELON_DIR = resolve(process.cwd(), '.gluon')
export const MELON_DIR = resolve(process.cwd(), '.surfer')
export const MELON_TMP_DIR = resolve(MELON_DIR, 'engine')
export const DIST_DIR = resolve(process.cwd(), 'dist')

View file

@ -1,7 +1,7 @@
import { config } from '..'
const otherBuildModes = `# You can change to other build modes by running:
# $ gluon set buildMode [dev|debug|release]`
# $ surfer set buildMode [dev|debug|release]`
const platformOptimize = getPlatformOptimiseFlags()
@ -38,7 +38,7 @@ ${platformOptimize} # Taken from waterfox`
return `
# =====================
# Internal gluon config
# Internal surfer config
# =====================
${buildOptions}

View file

@ -17,7 +17,7 @@ import { log } from './log'
// We have to use a dynamic require here, otherwise the typescript compiler
// mucks up the directory structure
// eslint-disable-next-line @typescript-eslint/no-var-requires, unicorn/prefer-module
const { version: gluonVersion } = require('../package.json')
const { version: surferVersion } = require('../package.json')
export const config = configInited
@ -61,7 +61,7 @@ program
reportedFFVersion ? `(being reported as ${reportedFFVersion})` : ''
}`,
},
{ name: 'Gluon', value: gluonVersion },
{ name: 'Gluon', value: surferVersion },
reportedFFVersion
? `Mismatch detected between expected Firefox version and the actual version.\nYou may have downloaded the source code using a different version and\nthen switched to another branch.`
: '',

View file

@ -128,10 +128,10 @@ class Log {
*/
askForReport(): void {
console.info(
'The following error is a bug. Please open an issue on the gluon issue structure with a link to your repository and the output from this command.'
'The following error is a bug. Please open an issue on the surfer issue structure with a link to your repository and the output from this command.'
)
console.info(
'The gluon issue tracker is located at: https://github.com/pulse-browser/gluon/issues'
'The surfer issue tracker is located at: https://github.com/zen-browser/surfer/issues'
)
}
}

2
src/types.d.ts vendored
View file

@ -7,7 +7,7 @@ export interface Cmd {
/**
* A function that returns the controller as a promise. We want to dynamically
* load them to reduce the startup time of gluon, which, at the time of
* load them to reduce the startup time of surfer, which, at the time of
* writing, is getting a touch long
*/
// eslint-disable-next-line @typescript-eslint/no-explicit-any

View file

@ -12,7 +12,7 @@ import { BIN_NAME } from '../constants'
import { log } from '../log'
export const projectDirectory = process.cwd()
export const configPath = join(projectDirectory, 'gluon.json')
export const configPath = join(projectDirectory, 'surfer.json')
let hasWarnedAboutConfig = false
@ -158,7 +158,7 @@ export const defaultLicenseConfig: LicenseConfig = {
}
export const defaultConfig: Config = {
name: 'Unknown gluon build',
name: 'Unknown surfer build',
vendor: 'Unknown',
appId: 'unknown.appid',
binaryName: 'firefox',

1
surfer.json Normal file
View file

@ -0,0 +1 @@
{}