Build and Modify uProxy

This document describes an exercise to set up your development environment to build uProxy from the source, and how to rebuild it in case of changes.

Setup required tools

This exercise assumes that you have already installed the development tools as described in the README file.

Get the source code

Let’s start with a new directory and clone the git repository:

mkdir -p $HOME/uproxy/codelab && cd $HOME/uproxy/codelab
git clone https://github.com/uProxy/uProxy.git .

Install the external build dependencies

There are a number of external dependencies that needs to be fetched, built and placed in the right place. You can do that with the setup.sh script:

./setup.sh install

This takes a little over a minute. After the first run, you only need to re-install the dependencies when the list of uProxy dependencies change. This may happen when you change them directly, or when you pull changes from the remote repository.

Build uProxy

To build uProxy, call

grunt

That will build uProxy for both Chrome and Firefox. It takes about 1 minute.

If you only want to build uProxy for Chrome, use

grunt build_chrome

The build output for Chrome will be under build/dev/uproxy/chrome:

ls build/dev/uproxy/chrome/{app,extension}

Install uProxy

Open chrome://extensions and load the two extensions you built. You can find instructions here: https://developer.chrome.com/extensions/getstarted#unpacked. Use the build/dev/uproxy/chrome/extension and build/dev/uproxy/chrome/app paths.

Start the application and check that it opens correctly.

Make a change

Let's make a few visible changes.

NOTE: This assumes your Chrome UI is in English.

Change the Chrome application name

1. Open src/chrome/app/_locales/en/messages.json
2. Change the appName message value to be "uProxy Chrome Application"

Change the Chrome extension name

1. Open src/chrome/extension/_locales/en/messages.json
2. Change the extName message value to be "uProxy Chrome Extension"

Change the window title

1. Open src/generic_ui/index.html
2. Change the title to <title>My Custom uProxy</title>

Change the header title

1. Open src/generic_ui/polymer/root.html
2. Change the title tag to <div id='title' flex>My Custom uProxy</div>

You can run git diff so see all your changes:

Rebuild

Let's rebuild to see the changes

grunt build_chrome

This run should be quicker than the first run, since it reuses some output that was not affected by the change. Notice also that you don't need to call setup.sh again.

In case of errors, you can try to fix them and try again.

Verify Changes

If you have the application open, you can press Ctrl+R to reload it. If the application is closed, it should show the change when you reopen it:

You can also see the change in the Chrome extensions list:

If the list doesn't show the new names, press Ctrl+R to refresh it.

Run Tests

Run the tests to make sure your change didn't break anything

grunt test

This will run the unit and integration tests. If you just want to run the unit tests, use

grunt unit_test