Introduction

This is a developer guide for QFeeds

The source code of the guide is in Markdown format, folder docs/, github.com/pmarinov/qfeeds/tree/master/docs

Contributions are welcome!

The guide is rendered in book format via mdBook, https://rust-lang.github.io/mdBook/

License

Written by Peter M., 2024-04-27, the text & code here are Public Domain

Build

QFeeds uses a Makefile to position sources for Chrome and Firefox browsers

Directory structure

2 types of folders -- unmodified (committed to version control) and build output (generated by Makefile)

Unmodified

chrome/ -- Files for integration into the chrome of the browser (icon, background.js, etc.)
qfeeds/ -- Main source code
docs/ -- Hacking QFeeds

Output folders

lib/ -- Source code of libraries is downloaded here
chrome-qfeeds/ -- Sources packages to run on Google Chrome
firefox-qfeeds/ -- Sources packaged to run on Mozilla Firefox

Build via make

First, run make libs, this populates folder lib/ by downloading and unpackaging the source code of all external libraries needed by QFeeds
Run make all, this populates folders chrome-qfeeds/ and firefox-qfeeds/.

Run make all every time after modifications of the source code to place the source files in the appropriate places for the 2 browsers.

Chrome browser

Steps to install, run, and debug on browser Google Chrome

Start Google Chrome browser
Invoke Menu | Tools | Extensions (or enter URL: chrome://extensions)
From page Extensions enable Developer mode
Click Load unpacked extension
Navigate to the directory chrome-qfeeds/, select the directory by name (contents of the extension is inside it)
The icon of QFeeds should appear in the areas for extensions

Firefox browser

There are two ways to work on extensions in Firefox.

The quick way is to load the extension temporarely for the duration of the current session. This has to be repeated every time Firefox is started, all data from the previous session is lost.

A persistent installation is better suited for the development work of QFeeds. The steps for that are:

Firefox Developer Edition

To be able to work with unsigned extension we need Firefox Developer Edition

Download: mozilla.org/en-US/firefox/developer/

Untar into a local folder:

mkdir -p ~/.local/bin
cd ~/.local/bin
tar -xvf ~/Downloads/firefox-60.0b3.tar.bz2

Start from that folder, this will also create the profile upon first start
```
cd ~/.local/bin/firefox
./firefox
```
Enable usigned extensions
- Enter URL about:config
- search for xpinstall.signatures.required
- Toggle it to false
Exit Firefox

Find the profile folder

$ cd ~/.mozilla/firefox/
$ find . -name \*dev-edition\*
./l062qyl2.dev-edition-default

$ cd l062qyl2.dev-edition-default/extensions/

Create a pointer file here, it should look like this:
```
$ cat \{2df366ca-28d2-11e8-9c70-b7b0d99bd061\}
/home/peterm/work/qfeeds/firefox-qfeeds/
```
Important considerations

Use full path to home folder, not ~
- The name of the pointer file matches the field id from manifest.json
- The trailing slash is important
- This pointer file is a left-over technique from the time of the now deprecated XUL-format extensions. It is described here: Setting up extension development environment (mozilla.org), see section "Firefox extension proxy file"
Activate the extension from page about:addons. Toggle the enable/disable switch-box button for extension QFeeds.
Once the setup of devel version is done Firefox Developer Edition can be started conveniently with:
```
$ (cd ~/.local/bin/firefox; ./firefox&)
```
To reload the extension after edits, Ctrl+R
To reload the extension after edits of manifest.json, restart Firefox Developer Edition
To be able to navigate the source files while in the Debugger set the option Enable browser and add-on debugging toolboxes to ON. Restart the browser.

Debug background.js

Navigate to the debugger via about:debugging#/runtime/this-firefox, click button Inspect for QFeeds -- this is the only way to debug backgrund.js
Use the log filter, to isolate the messages type background
To activate edits of background.js, go to about:addons and disable and enable the extension while the debugger window is closed

Debug functions

From the browser's console can be invoked a list of debug functions

Force fresh reload of remote feeds

Objectives:

Delete local IndexedDB of subscribed feeds
Reset cached version ID of the remote table

Invocation:

>> feeds_ns.app.m_feedsDir.m_feedsDB.feedUnsubscribeAll()
[Debug] Delete all subscriptions from IndexedDB...'
[Debug] Done, deleted 8 RSS subsciptions

>> feeds_ns.app.m_feedsDir.m_feedsDB.feedResetRTableConnection()

Close and re-open the extension. It should load all remote entries into local IndexedDB

Add example entries

Invocation:

>> feeds_ns.app.m_feedsDir.m_feedsDB.feedAddByUrl1()
[Debug] Added https://...

>> feeds_ns.app.m_feedsDir.m_feedsDB.feedAddByUrl2()
[Debug] Added https://...

Unsubscribe All

Invocation:

>> feeds_ns.app.m_feedsDir.m_feedsDB.feedUnsubscribeAll(true)
[Debug] Delete all subscriptions from IndexedDB, remoteSync: true
[Debug] Done, deleted 2 RSS subsciptions

Hacking QFeeds