Build and Modify uProxy

This document describes an exercise to build uProxy from the source and how to rebuild it after a change.

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 follow the instructions on https://developer.chrome.com/extensions/getstarted#unpacked to install local unpacked extensions. You'll find them at:

• ~/uproxy/codelab/build/dev/uproxy/chrome/extension
• ~/uproxy/codelab/build/dev/uproxy/chrome/app

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

Clean up

Once you are done with the exercise, you can uninstall the extensions and delete the ~uproxy/codelab directory.