📝 Update docs

This commit is contained in:
trickypr 2022-06-17 15:25:23 +10:00
parent 41bb9e9561
commit d6b9616ef4
7 changed files with 33 additions and 79 deletions

View file

@ -19,8 +19,8 @@ build_search_index = true
highlight_code = true
[extra]
# TODO: New logo
release = "https://api.github.com/repos/focus-browser/build/releases/latest"
logo = "https://twemoji.maxcdn.com/v/13.0.1/svg/1f4e6.svg"
release = "https://api.github.com/repos/pulse-browser/gluon/releases/latest"
[author]
name = "TrickyPR"

View file

@ -3,6 +3,6 @@ title = "index"
insert_anchor_links = "right"
+++
## Welcome to the melon docs
## Welcome to the Gluon docs
If you are new here, you should read the [Getting Started](./getting-started/overview/) guide.

View file

@ -3,35 +3,35 @@ title = "Overview"
weight = 5
+++
## Getting started with melon
## Getting started with gluon
### What is melon
### What is gluon
Melon 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.
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 melon in general, please contact us. You can [create a discussion on github](https://github.com/dothq/melon/discussions/new), ping @trickypr on the [Dot HQ discord](https://dothq.link/dsc), or [join our Matrix chat](https://dothq.link/matrix).
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).
### System requirements
- **OS**: Linux and MacOS (If you are using windows, take a look at the [Windows Guide](../windows/))
- **Melon dependencies**: NodeJS and npm
- **Browser dependencies**: TODO: find out what firefox's build dependencies are
- **Gluon dependencies**: NodeJS and npm
- **Browser dependencies**: Will be handled by bootstrapping
### Getting started
The first thing you are going to need to do is to install melon. As it is a nodejs program it can be installed through npm or yarn.
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 melon-build
npm install -g gluon-build
# or
yarn global add melon-build
yarn global add gluon-build
# 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 `melon setup-project` inside of that repo. 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.
Now create a git repo and clone it to your local machine. Then run `gluon setup-project` inside of that repo. 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.
- `Firefox nightly`: Updates every 12 hours, making it almost impossible to keep up to date **(not recommended)**
- `Firefox beta`: Updates every 4 weeks. It will have unresolved bugs **(not recommended)**
@ -40,38 +40,44 @@ Now create a git repo and clone it to your local machine. Then run `melon setup-
- `Firefox extended support release (newer)`: The latest extended support release. Releases around once every 8 stable cycles (mozilla isn't clear on this). Receives regular small security patches and bug fixes, but no large breaking changes (e.g. [proton](https://www.omgubuntu.co.uk/2021/02/try-firefox-proton-redesign-ubuntu)) between releases.
- `Firefox extended support release (newer)`: The oldest supported extended support release. Maximum security and stability, but will lose support sooner than the newer extended support release.
Dot browser currently uses the stable releases, and keeping up to date can be a struggle with a small development team.
Pulse Browser currently uses the stable releases, and keeping up to date can be a struggle with a small development team.
Then next is the version of the browser you want to use. By default melon will populate this with the latest version available, which we recommend using.
Next it will ask for the name of your browser. Avoid references to firefox or other mozilla brands if you can.
Next it will ask for the name of your browser. Avoid references to Firefox or other Mozilla brands if you can.
Vendor is the company (or solo developer) who is creating the browser.
The appid follows reverse dns naming conventions. For example, DotHQ owns the domain `dothq.co`, so our browser is `co.dothq.browser`. If you do not have a domain, you can use your username / psudomim as the appid, e.g. `trickypr.watermelon`.
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 / psudomim as the appid, e.g. `trickypr.watermelon`.
Next you need to chose a starting template for your browser. You can go with userchrome, where you apply css changes to firefox or custom html, where you have to write everything (tabs, navigation, search boxes) yourself. We generally recommend userchrome for new users, as it has the lowest learning curve. Additionally, you can chose to use no template.
Now you have created the directory structure for your project, you can build it for the first time. First, ask melon to download the firefox source.
```sh
melon download
gluon 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
```
After the source code has been downloaded, the changes to firefox described in the source code must be applied.
```sh
melon import
gluon 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
melon build
gluon build
```
Now you can finally start the browser!
```sh
melon run
gluon run
```

View file

@ -3,13 +3,13 @@ title = "Userchrome"
weight = 15
+++
This page will explain the process for applying custom css (or userchrome) to your new browser. I expect you to have already setup melon as described in the overview and have something that looks like the following on your screen.
This page will explain the process for applying custom css (or userchrome) to your new browser. I expect you to have already setup gluon as described in the overview and have something that looks like the following on your screen.
![Firefox build without branding](https://cdn.statically.io/img/dothq.github.io/f=auto/melon/images/userchrome/css-basic.png)
The firefox window shown above is constructed from (x)html, styled with css and made dynamic with javascript. This means that the entire browser can be styled with custom css, called userchrome.
If you selected the userchrome option when setting up the project, melon will have already created the theme files for you. `src/browser/themes/custom/shared/shared.inc.css` will be included on all platforms, whilst platform specific styles will be included from similar files in `src/browser/themes/custom`.
If you selected the userchrome option when setting up the project, gluon will have already created the theme files for you. `src/browser/themes/custom/shared/shared.inc.css` will be included on all platforms, whilst platform specific styles will be included from similar files in `src/browser/themes/custom`.
Additionally, firefox has an equivalent to "inspect element", but for the browser. Click on the hamburger menu, select "More tools", then "Browser toolbox" to open it.

View file

@ -5,7 +5,7 @@ weight = 10
# Including addons
Melon 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 (`melon.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 (`gluon.json`).
```json
{
@ -84,5 +84,5 @@ let navbarPlacements = [
Finally, export the changes you have made:
```sh
melon export-file browser/components/customizableui/CustomizableUI.jsm
gluon export-file browser/components/customizableui/CustomizableUI.jsm
```

View file

@ -5,7 +5,7 @@ weight = 5
# Removing pocket
**Note:** This expects you have melon setup.
**Note:** This expects you have gluon setup.
## Disabling in firefox.js
@ -42,7 +42,7 @@ user_pref(
Now you simply need to export the changes made to `firefox.js`:
```sh
melon export-file browser/app/profile/firefox.js
gluon 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
melon export-file browser/components/customizableui/CustomizableUI.jsm
gluon export-file browser/components/customizableui/CustomizableUI.jsm
```

View file

@ -1,52 +0,0 @@
+++
title = "Forcing windows to work"
weight = 10
+++
## Steps followed to get installing on windows to work
1. Install build tools for Visual Studio
- Desktop development with c++
- Windows 10 sdk (at least 10.0.19041.0).
- C++ ATL for v143 build tools (your architecture)
2. Install git for windows: https://git-scm.com/download/win
- Configuring the line ending conversions **must be**: Checkout as-is, commit as-is
- Enable experimental built-in file system monitor
3. Install mozilla build. See mozillas documentation
4. Install Nodejs and yarn - This should install chocoalaty
5. Clone pulse recursivly (cmd)
6. Install dependancies `yarn`
7. Create link `yarn setupLink:win`
8. Disabled anti-malware on 'C:\mozilla-build' and working directory to reduce system load
9. download and init
10. import patches
11. ./mach boostrap in engine
12. choco install make
13. yarn build
14. ./mach build
## Fixing UI bugs
TODO: flesh this out
Without a correct manifest file, windows will report on windows 8 on windows 10 / 11, leading to a variety of UI bugs.
## Notes to future self
- Try running commands in MozillaBuild shell rather than windows cmd
- Tests need to be disabled by default, they take up too much build time
## Bootstrap freezes in a CI environment
We use mach bootstrap within our CI environments without initing it as a git repo. Under normal circumstances bootstrap will error (on windows boostrap freezes without using the CI )
## TODO:
### UI
- [ ] Fix titlebar buttons - Caused by firefox thinking I am on windows 8
### Build
- [ ] Test to see if git in git-bash / mozilla's terminal is faster
- [ ] Use git-bash / mozilla terminal for git
- [ ] Make sure yarn build works