uProxy is a browser extension that lets users share their internet connection.
uProxy is built using the following tools:
- Grunt to write the tasks that build uProxy
- TypeScript as the primary language we code in; this compiles to JavaScript. It gives us type-checking and has some syntax improvements on JS, while letting us incrementally migrate and easily include external JS packages and frameworks.
- Jasmine for testing
- Polymer for UI
- Travis for continuous integration
- Shippable for docker-integrated continuous integration
To manage dependencies we use:
- npm to install node modules that we use for our build process. (Specified in
package.json
) - Bower to install libraries that we use in the UI
(specified in
bower.json
) including Polymer.
Please read the uProxy Coding Guide to learn more about contributing to uProxy. For a high level technical overview of uProxy, see the uProxy Design Doc.
Note: you will either need to run these as root, or set the directories they
modify (/usr/local
) to being editable by your user (sudo chown -R $USER /usr/local
)
-
- Most machines will have git pre-installed. If you need to install git, you can find instructions from the git website.
- For Windows, install the desktop git app, which provides an easy-to-use interface for git.
-
node and npm (Node's package manager):
-
On Mac with Brew, you can do:
brew install node
(You may need to update your brew package manager, e.g.brew update
). You can also install directly from a Mac package off the NodeJS Website.- If you do not have Homebrew, you can install it by running
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
- If you do not have Homebrew, you can install it by running
-
On Ubuntu, you can do
apt-get install nodejs
. -
You may need to create a symlink (if we are not running legacy node)
Use this:
ln -s /usr/bin/nodejs /usr/bin/node -
On Archlinux, you can do 'pacman -S nodejs'.
-
On Windows, you can download the installer from the NodeJS Website.
-
You may need to set your
$NODE_PATH
environment variable appropriately (e.g. it might be:/usr/local/share/npm/lib/node_modules
). -
To run binaries from globally-installed npm packages without fully-qualifying paths, make sure you have added your npm bin directory to your path
- on Mac or Ubuntu, e.g.
export PATH=$PATH:/usr/local/share/npm/bin/grunt
- on Windows,
- Open Control Panel > System and Security > System > Advanced System Settings
- In the Advanced tab, click on "Environment Variables"
- In System Variables, click on "Path" (or "PATH")
- At the end of the "Variable value:" string, append a ";" and the path to your bin directory, e.g. "C:\Program Files\nodejs\node_modules\npm\lib;C:\Users<YOUR_PATH>\AppData\Roaming\npm\node_modules\grunt-cli\bin"
- on Mac or Ubuntu, e.g.
-
-
Grunt: Install globally with
npm install -g grunt-cli
- To install globally on Windows, open the command prompt as admin and then run the command
-
In your terminal, navigate to a directory where you would like to download uProxy. E.g.,
cd ~/uProxy
-
Clone the uProxy repository:
git clone https://github.com/uProxy/uProxy.git
orgit clone git@github.com:uProxy/uproxy.git
if you have your ssh access to GitHub set up (useful if you use 2-step auth for GitHub, which you should do). -
Navigate into uProxy's root directory with
cd uproxy
-
Setup build tools and third-party dependencies:
- In OS X or Linux, run
./setup.sh install
- In Windows, run
.\setup.cmd install
instead (in cmd or PowerShell).
- Run
grunt
- this will build everything, including uProxy for Chrome and Firefox.
Note that if any local dependencies have changed (i.e. changes to bower dependencies, updates to FreeDOM), you will have to run ./setup.sh install
to update these dependencies, then rerun grunt
These are the steps to try uProxy in the Chrome browser.
- In Chrome, go to
chrome://extensions
, make sure 'Developer mode' is enabled - Click 'Load unpacked extension...' and select
build/dev/uproxy/chrome/app
- Click 'Load unpacked extension...' and select
build/dev/uproxy/chrome/extension
You need both the uProxy Chrome App and the uProxy Extension.
You can use grunt build_chrome
from the root directory of the repository to re-compile just Chrome components.
These are the steps to try uProxy in the Firefox browser.
-
To run the add-on you need to have the Firefox add-on SDK installed. Instructions can be found here: https://developer.mozilla.org/en-US/Add-ons/SDK/Tutorials/Installation
- A quick way to get started is to download/extract the zip mentioned in "Prerequisites"
-
Run
cd build/dev/uproxy/firefox
-
Run
cfx run
and Firefox should launch with the uProxy add-on installed
You can use grunt build_firefox
from the root directory of the repository to compile just Firefox comonents.
uProxy uses the Grunt build system for its build tasks. Here is a list of uProxy's Grunt commands:
build
- Builds everything, making stuff in thebuild
directory (and runs tests).build_chrome
- Build Chrome app and extension *build_chrome_app
- Build just Chrome app *build_chrome_ext
- Build just Chrome extensionbuild_firefox
- Build just Firefoxdist
- Generates distribution files, including the Firefox xpiclean
- Cleans uptest
- Run unit testsintegration_test
- Run integration testseverything
- 'build', 'test' and then 'integration_test'
The easiest way to stay current is to pull changes, run grunt build
to build
your distribution, and re-run as you make changes to the files.
Before submitting any changes to the repository, make sure to run grunt test
to make sure it passes all unit tests. Failing tests are enough to immediately
reject submissions. :)
uProxy can now be built as an Android App, using the Cordova Chrome Apps (CCA) tool, also known as the Chrome Apps for Mobile Toolchain. After following the steps under "Building uProxy from source",
- Install the Android SDK. The easiest way to get it is as part of Android Studio.
- Linux-only Add the Android tools to your path, e.g. by modifying your
.bashrc
to includePATH=$PATH:$HOME/android-studio/tools
.
- Install the
adb
tool.
- MacOS:
adb
is included with Android Studio. - Linux:
adb
is available through your package manager. For example, on Ubuntu runapt-get install android-tools-adb
.
- Confirm that your
cca
package is ready by runningnode_modules/.bin/cca checkenv
from the git checkout root directory.
- If this fails, set the
ANDROID_HOME
variable to the Android SDK path in your.bashrc
, e.g.export ANDROID_HOME=$HOME/Android/Sdk
Then you can build the app using grunt build_android
. The output, a file ending
in .apk
, will appear in build/dev/uproxy/android/platforms/android/build/outputs/apk/
.
Depending on the build configuration, the file might be named android-debug.apk
,
android-armv7-debug.apk
, etc..
- To install the app, first Enable USB Debugging on your test phone, then connect it to your computer and accept the connection on the phone.
- Then, on your computer, install the app on the phone using a command like
adb install -r build/dev/uproxy/android/platforms/android/build/outputs/apk/android-debug.apk
. - You may then launch the app from the phone. Rerunning this command should close the app and replace it with a new version, but will not overwrite saved state on the device.
If you encounter an error or want to complete delete uProxy from your phone, you can do so via
Settings -> Apps -> uProxy
, which as a button labeled "Uninstall for all users".
- Create a virtual device using the Android Virtual Device Manager with an API of 21 (Lollipop) or higher.
- Launch the emulator and check
adb devices
at the command line to make sure an emulator is running. - Install the app from the command line with
adb install -r build/dev/uproxy/android/platforms/android/build/outputs/apk/android-debug.apk
. You should seesuccess
if the app is installed. - You may then launch the app from the emulator.
-
If something is going wrong during the build process, please try running
grunt clean
,./setup.sh clean
, and re-running./setup.sh install
-
If things are not working, check that you have recent versions of bower, npm, and node.
Configuration and setup files
Gruntfile.js
a file that specifies common tasks, e.g. how to build and package uProxy.bower.json
specifies dependent libraries from Bower.package.json
specifies dependent libraries from NPM..gitignore
what git should ignore.bowerrc
tells bower where to put files.travis.yml
Travis auto-testingtools
directory contains some typescript and javascript to help Grunt.third_party/tsd.json
specifies the typescript definitions to use
Source code
src
holds all source code; no compiled filessrc/generic_ui
generic user interface codesrc/generic_core
generic uproxy core-functionality codesrc/chrome/app
code specific to the chrome appsrc/chrome/extension
code specific to the chrome extensionsrc/firefox
code specific to firefoxthird_party
holds external libraries we depend on that are copied into this repositorynode_modules
dynamically generated npm module dependenciesscraps
temporary holding for sharing scraps of code
Dynamically created directories (grunt clean
should remove them)
build
created by grunt tasks; holds the built code, but none of the code that was compiled.build/dist
created by grunt tasks; holds final distribution versions.grunt
holds grunt cache stuff.tscache
holds typescript cache stuff