Building the extension

Building the extension/creating a development environment

We've created an automated script called make_release.py, which you can find in the /tools directory of the source code. This script can make a final build of CatBlock, like you'd find on the addon stores or the Releases page; or it can make an unpacked environment for testing code, with any unneeded Git cruft removed.

Requirements

• Python 3.x (the script does not work with Python 2.x)

Examples

Creating a packed extension

As an example, let's build CatBlock for Google Chrome, as if we were to upload it to the Chrome Web Store (so we'd need a ZIP file instead of a packed CRX). Just navigate to the root of the repository in a terminal and run the following command:

python3 tools/make_release.py -b chrome -ext zip
(N.B. Windows users may have to add C:\Python3\bin (or wherever the python3.exe is located to their %PATH%)

This will create a ZIP file in a folder called builds. If we instead replaced zip in that command with browser, we would get a CRX for manually loading into the browser (by drag-and-dropping onto chrome://extensions).

Creating a development environment

Lets assume we're still using Chrome, and want to test a branch we've been asked to review, but want it in a separate directory for testing.

As before, we'll have our terminal in the root of the repository, and we'll run this command:

python3 tools/make_release.py -b chrome -devenv

The development environment will be created as a folder with name catblock_chrome in the root of the project directory.

Arguments

This script accepts 4 arguments:

• -b, --browser (required)

  • Specifies which browser you want built. Can be one of chrome, firefox, opera, edge or all

• -ext, --extension (optional, when -devenv is included; otherwise required)

  • Specifies that we want a packed extension to be generated. Can be one of browser or zip
  • NOTE: CatBlock for Edge is always generated as a ZIP, since a tool for converting extensions to the .appx format is not publicly available (yet).

• -devenv (optional)

  • When included, development environment will be created

• --updatelangs (optional)

  • When included, script will attempt to update all language files

Sideloading CatBlock

We strongly recommend, that you install CatBlock from official extensions stores but feel free to sideload CatBlock and see, how it works!

There's also a bleeding-edge version of CatBlock called, CatBlock Nightly, which has the latest changes contained within. These are stored in their own dedicated repository. We're working on having them automatically uploaded to their respective stores so that we can automatically update them.

Alright, let's proceed to the sideloading!

First, you will need to:

• either create an unpacked development environment (by specifying -devenv in the command)
• or generate a packed extension (by specifying -ext browser)

In Google Chrome

When you've generated an unpacked development environment:

1. Go to the Chrome menu > Tools > Extensions
2. Check Developer mode then press Load unpacked extension...
3. Select the generated catblock_chrome folder in the project directory
4. That's it!

When you've generated a packed extension:

1. Navigate to chrome://extensions page
2. Navigate to /builds folder and locate catblock-chrome.crx file
3. Drag the catblock-chrome.crx file and drop it to the Extensions page you've opened in the first step
4. That's it!

In Opera

When you've generated an unpacked development environment:

1. Navigate to opera://extensions
2. Press Developer Mode button and then press Load Unpacked Extension... button
3. Select the generated catblock_opera folder in the project directory
4. That's it!

When you've generated a packed extension:

1. Open opera://extensions page
2. Navigate to /builds folder and locate catblock-opera.nex file
3. Drag catblock-opera.nex file and drop it to the Extensions page you've opened in the first step
4. That's it!

In Firefox

When you've generated an unpacked development environment:

1. Navigate to about:debugging page
2. Tick Enable add-on debugging option
3. Click on Load Temporary Add-on button
4. Select the generated catblock_firefox folder in the project directory
5. That's it!

When you've generated a packed extension:

2. Make sure that you are running Firefox Developer Edition or Firefox Nightly!
3. Go to about:config and set xpinstall.signatures.required to false
4. Go to about:addons => click on settings icon
5. Select Install Add-on from file...
6. Select catblock-firefox.xpi file
7. That's it!

In Microsoft Edge

NOTE: Currently, there is no way, how to generate a packaged .appx extension/application for Microsoft Edge browser for 3rd party developers.

When you've created an unpacked development environment:

1. Navigate to catblock_edge folder
2. Run Setup.cmd file
3. Start up Edge, open up about:flags page
4. Make sure that checkbox next to Enable extension developer features is selected
5. Restart Edge
6. Click on three dots (...) and then on Extensions in menu
7. Click on Load extension
8. Select unpacked "catblock" folder

After each startup of Edge browser, you won't immediately see CatBlock as an installed extension, because it hasn't been signed and released to the Windows Store. After about 10 seconds you should get a prompt asking whether you want to load unsigned extensions or not. Say yes.