README ¶
Lantern on Android
import go.flashlight.Flashlight;
The lantern-android
repository provides documentation and scripts for
building a basic lantern shared library that exports special methods
that can be used from Java code, making it possible to run the lantern
backend on Android devices.
try {
Flashlight.RunClientProxy("0.0.0.0:9192");
} catch (Exception e) {
throw new RuntimeException(e);
}
Prerequisites
- An OSX or Linux box
- docker
- Android Studio
- Go 1.4
- GNUMake
- Mercurial: You can try installing it with
brew
ormacports
.
Setting up a development environment
We're going to clone and use the lantern repository, that project provides us with everything we need to build Lantern tools and libraries.
mkdir -p $GOPATH/src/github.com/getlantern
cd $GOPATH/src/github.com/getlantern
git clone https://github.com/getlantern/lantern.git
After cloning the repository use the setenv.bash
script to export development
enviromental variables to the current terminal session.
cd lantern
source setenv.bash
Building the Android library
lantern
will provide you with a copy of lantern-android
, change
directory into lantern-android
and execute make
to start compiling our
shared library:
cd $GOPATH/src/github.com/getlantern/lantern-android
make
# ...
# BUILD SUCCESSFUL
# Total time: 7 seconds
The make
command will create a new app
subdirectory that will contain an
Android example project. You may import the contents of the app
subdirectory
into Android Studio to see libflashlight working.
If you're on a Mac, be sure to export docker's enviromental variables before
running make
:
$(boot2docker shellinit)
make
Testing the example project
Open Android Studio and in the welcome screen choose "Import Non-Android Studio project".
You'll be prompted with a file dialog, browse to the app
subdirectory and
select it. Press OK.
On the next dialog you must define a destination for the project, hit Next.
After import you may be prompted to restart Android Studio.
Now add a new main activity by right-clicking on the top most directory on the Project pane and selecting New->Activity->Blank Activity, the default values would be OK, click Finish.
Paste the following code on the org.getlantern/example/MainActivity.java
file
that was just added:
package org.getlantern.example;
import go.Go;
import go.flashlight.Flashlight;
import android.app.Activity;
import android.os.Bundle;
import android.util.Log;
import android.view.View;
import android.widget.Button;
import org.getlantern.example.R;
public class MainActivity extends Activity {
private Button killButton;
private Button startButton;
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
// Initializing application context.
Go.init(getApplicationContext());
killButton = (Button)findViewById(R.id.stopProxyButton);
startButton = (Button)findViewById(R.id.startProxyButton);
// Disabling stop button.
killButton.setEnabled(false);
// Enabling proxy button.
startButton.setEnabled(true);
}
public void stopProxyButtonOnClick(View v) {
Log.v("DEBUG", "Attempt to stop running proxy.");
try {
Flashlight.StopClientProxy();
} catch (Exception e) {
throw new RuntimeException(e);
};
// Disabling stop button.
killButton.setEnabled(false);
// Enabling proxy button.
startButton.setEnabled(true);
}
public void startProxyButtonOnClick(View v) {
Log.v("DEBUG", "Attempt to run client proxy on :9192");
try {
Flashlight.RunClientProxy("0.0.0.0:9192");
} catch (Exception e) {
throw new RuntimeException(e);
}
// Enabling stop button.
killButton.setEnabled(true);
// Disabling proxy button.
startButton.setEnabled(false);
}
}
After this new activity is added the design view will be active, drag two buttons from the Pallete into the screen.
Select the first button and look for the id property on the Properties pane, set it to startProxyButton and name the button accordingly. Look for the onClick property and choose the startProxyButtonOnClick value from the drop down.
The second button's id must be set to stopProxyButton and the onClick to stopProxyButtonOnClick.
Finally, hit the Run app action under the Run menu and deploy it to a real device or to an ARM-based emulator (armeabi-v7a).
I you're having configuration related problems when attempting to build, make
sure your AndroidManifest.xml
looks like this:
<?xml version="1.0" encoding="utf-8"?>
<!--
Copyright 2014 The Go Authors. All rights reserved.
Use of this source code is governed by a BSD-style
license that can be found in the LICENSE file.
-->
<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="org.getlantern.example" android:versionCode="1" android:versionName="1.0">
<application android:label="Flashlight">
<activity android:name="org.getlantern.example.MainActivity"
android:label="Flashlight"
android:exported="true">
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
</activity>
</application>
<uses-permission android:name="android.permission.INTERNET" />
</manifest>
If everything goes OK, you'll have two buttons and you can start lantern
by touching the startProxyButton.
As long as the app is open, you'll be able to test the canonical example by finding the device's IP and sending it a special request:
curl -x 10.10.100.97:9192 http://www.google.com/humans.txt
# Google is built by a large team of engineers, designers, researchers, robots, and others in many different sites across the globe. It is updated continuously, and built with more tools and technologies than we can shake a stick at. If you'd like to help us out, see google.com/careers.
You may not want everyone proxying through your phone! Tune the
RunClientProxy()
function on the MainActivity.java
accordingly.
If you chose to run flashlight inside an emulator instead of a real device, you must connect to it using telnet and set up port redirection to actually test the proxy.
Identify the port number your emulator is listening to
In this case its listening on the 5554
local port.
Open a telnet session to the emulator and write the instruction redir add tcp:9192:9192
to map the emulator's 9192
port to our local 9192
port.
telnet 127.0.0.1 5554
# Trying 127.0.0.1...
# Connected to localhost.
# Escape character is '^]'.
# Android Console: type 'help' for a list of commands
# OK
redir add tcp:9192:9192
# OK
Now you'll be able to connect to the emulator's lantern proxy through your
local 9192
port:
curl -x 127.0.0.1:9192 https://www.google.com/humans.txt
# Google is built by a large team of engineers, designers, researchers, robots, and others in many different sites across the globe. It is updated continuously, and built with more tools and technologies than we can shake a stick at. If you'd like to help us out, see google.com/careers.
Directories ¶
Path | Synopsis |
---|---|
main package holds references to the go_bindings package and is based on instructions from http://godoc.org/golang.org/x/mobile/cmd/gobind
|
main package holds references to the go_bindings package and is based on instructions from http://godoc.org/golang.org/x/mobile/cmd/gobind |
bindings/go_bindings
Package go_flashlight is an autogenerated binder stub for package flashlight.
|
Package go_flashlight is an autogenerated binder stub for package flashlight. |