Permalink
Browse files

Improvements to documentation and ponyd installation

Improved and finished several features:

* devtools installation is done inside the virtualenv now
* better symlink error handling
* made pony listen on localhost by default
* Updated documentation
  • Loading branch information...
1 parent 63ffc12 commit 4290b6626e63140879c2a8f156fa855cabc8f284 @mikelikespie mikelikespie committed Aug 30, 2012
Showing with 105 additions and 41 deletions.
  1. +78 −20 README_ponyd.rst
  2. +2 −2 ponyd/constants.py
  3. +7 −12 ponyd/downloader.py
  4. +6 −3 ponyd/gateway.py
  5. +12 −4 scripts/_bootstrap_contents.py
View
@@ -1,41 +1,99 @@
-
-PonyGateway: PonyDebugger Gateway Server
-========================================
+PonyGateway: PonyDebugger Gateway Server (``ponyd``)
+====================================================
This directory contains the gateway server that serves Chrome Developer Tools.
-PonyGateway is licensed under the Apache Licence, Version 2.0 (http://www.apache.org/licenses/LICENSE-2.0.html).
+PonyGateway is licensed under the Apache Licence, Version 2.0
+(http://www.apache.org/licenses/LICENSE-2.0.html).
Installing
----------
-- To install the latest stable version:
+There are two ways to install both are pretty simple and can be run in userland.
+The end result is the same.
+
+Quick userland install
+``````````````````````
+
+::
+
+ curl -sk https://cloud.github.com/downloads/square/PonyDebugger/bootstrap-ponyd.py | \
+ python - --ponyd-symlink=/usr/local/bin/ponyd ~/Library/PonyDebugger
+
+This will install ``ponyd`` script to ``~/Library/PonyDebugger/bin/ponyd`` and
+attempt to symlink ``/usr/local/bin/ponyd`` to it.
+
+This installer uses a `virtualenv
+<http://www.virtualenv.org/en/latest/index.html>`_ bootstrap script to install
+PonyDebugger and all its dependencies in an isolated python environment in
+``~/Library/PonyDebugger``.
+
+Since this uses virtualenv, you can also download the script and customize the
+installation options::
+
+ curl -O https://cloud.github.com/downloads/square/PonyDebugger/bootstrap-ponyd.py
+ python bootstrap-ponyd.py --help
+
+Upgrading your installation can be done with the following commands::
+
+ # activate your virtualenv
+ source ~/Library/PonyDebugger/bin/activate
+ # update the ponyd source
+ pip install -U -e git+https://github.com/square/PonyDebugger.git#egg=ponydebugger
+ # updates chrome dev tools source
+ ponyd update-devtools
+
+.. Note:: This process will be simplified in the future
+
+
+Development installation
+````````````````````````
+
+If you already have PonyDebugger git repo checked out you can can set up a
+virtualenv manually and have your ponyd installation point to your existing
+checkout. For demonstration we assume ``$VENV`` is set to your intended install
+path and ``$PONYDEBUGGER_PATH`` is set to your PonyDebugger git checkout::
+
+ # if you don't already have virtualenv installed
+ sudo easy_install virtualenv
+
+ virtualenv "$VENV"
+ source "$VENV/bin/activate"
+ pip install -e "$PONYDEBUGGER_PATH"
+
+ # to ensure your shell knows ponyd exists
+ hash -r
+
+To run this ponyd you can either activate your environment by ``source
+"$VENV/bin/activate"`` and ``ponyd`` will be added to your path. You can also
+just call it directly via ``$VENV/bin/ponyd`` without activating first.
- ``sudo pip install ponygateway``
- Or omit sudo if installing in a virtual environment.
+Starting Debugging Server
+-------------------------
- **Note**: If you want to download the latest version, you will have to clone the repository and run ``sudo python setup.py install`` in the ``ponygateway`` directory.
+Once installed, running PonyDebugger's server is easy::
-- Install a supported version of Chrome Developer Tools with ``ponydownloader``.
+ ponyd serve
- This will install a supported version of Chrome Developer Tools into ``~/.devtools`` by default. To specify a custom directory:
+By default, ponyd listens on port 9000 and only on your localhost for security
+reasons.
- ``ponydownloader /path/to/devtools``
+To make the server accessible by another device or computer you must have ponyd
+listen on ``0.0.0.0`` which is done by::
-- To run the Gateway server, run ``ponygateway``. By default, this will run the
- gateway on ``localhost:9000``.
-
- To specify a custom devtools directory:
+ ponyd serve -i 0.0.0.0
- ``ponygateway -d /path/to/devtools``
+The listen and other ports can be customized as well. Run ``ponyd serve
+--help`` for more information.
- For more details, run ``ponygateway -h``
Known Issues / Improvements
---------------------------
-- Relaunching the client application requires you to navigate back to the main page.
-- Chrome Developer Tools shows some unnecessary tabs (such as Elements). ``ponydownloader`` could possibly be
- updated to patch the incoming chrome developer tools to hide these unused tabs.
+- Relaunching the client application requires you to navigate back to the main
+ page.
+- Chrome Developer Tools shows some unnecessary tabs (such as Elements).
+ ``ponyd update-devtools`` could possibly be updated to patch the incoming
+ chrome developer tools to hide these unused tabs.
View
@@ -1,5 +1,5 @@
import os
+import sys
-DEFAULT_DEVTOOLS_PATH = os.path.expanduser('~/.devtools')
-
+DEFAULT_DEVTOOLS_PATH = os.path.abspath(os.path.join(os.path.dirname(os.path.abspath(sys.argv[0])), '..', 'src', 'devtools'))
View
@@ -18,24 +18,13 @@ class Downloader(PonydCommand):
__subcommand__ = 'update-devtools'
dirname = Arg(nargs='?',
- help='path to download and extract devtools',
+ help='path to download and extract devtools (default: %s)' % DEFAULT_DEVTOOLS_PATH,
default=DEFAULT_DEVTOOLS_PATH)
- force = Arg('-f', '--force',
- help='if dirname already exists, then replace directory',
- action='store_true')
latest = Arg('-l', '--latest',
help='install the lastest dev tools instead of a known good version',
action='store_true')
def __call__(self):
- if os.path.exists(self.dirname):
- if self.force:
- print "Removing directory", os.path.abspath(self.dirname)
- shutil.rmtree(self.dirname)
- else:
- print "Directory %s exists. Run with --force (-f) to overwrite the directory." % self.dirname
- return
-
if self.latest:
version = urllib2.urlopen(LATEST_URL).read()
else:
@@ -46,9 +35,15 @@ def __call__(self):
tools_stream = StringIO(urllib2.urlopen(tools_url).read())
+
+ if os.path.exists(self.dirname):
+ print "Removing existing devtools installation at %s" % self.dirname
+ shutil.rmtree(self.dirname)
+
extract_dir = self.dirname
print "Extracting to %s" % extract_dir
tools_zip = zipfile.ZipFile(tools_stream, 'r')
tools_zip.extractall(path=extract_dir)
+
View
@@ -63,7 +63,8 @@ def devToolsConnected(self, devTools):
if device.page == devTools.page:
devTools.waiting = False
- logger.info("Dev tools connecting to device %s", device.deviceID)
+ logger.info("Dev tools connecting to device %s",
+ device.deviceID)
devTools.device = device
device.devTools = devTools
break
@@ -123,7 +124,9 @@ def _registerDevice(self, params):
self.app_state.registerDevice(self)
# Announce existence.
- logger.info("Device %s Registered (%s, %s)" % (self.deviceID, self.device_model, self.device_name))
+ logger.info("Device %s Registered (%s, %s)" % (self.deviceID,
+ self.device_model,
+ self.device_name))
@property
def deviceInfo(self):
@@ -207,7 +210,7 @@ class Gateway(PonydCommand):
listen_interface = Arg('-i', '--listen-interface',
help='interface to listen on. [default: %(default)s]',
- default='0.0.0.0',
+ default='127.0.0.1',
metavar='IFACE')
def __call__(self):
@@ -11,12 +11,20 @@ def after_install(options, home_dir):
ponyd_path = join(home_dir, 'bin', 'ponyd')
- if options.ponyd_symlink:
+
+ symlink_target = options.ponyd_symlink
+
+ if symlink_target:
+ if os.path.isdir(symlink_target):
+ symlink_target = os.path.join(symlink_target, 'ponyd')
+
+ if os.path.exists(symlink_target):
+ print "Symlink to %s already exists. (continuing anyways)" % symlink_target
try:
- print "Symlinking %s to %s" % (ponyd_path, options.ponyd_symlink)
- os.symlink(ponyd_path, options.ponyd_symlink)
+ print "Symlinking %s to %s" % (ponyd_path, symlink_target)
+ os.symlink(ponyd_path, symlink_target)
except:
- print >>sys.stderr, "Error creating symlink"
+ print >>sys.stderr, "Error creating symlink. Manually run: sudo ln -s '%s' '%s'" % (ponyd_path, symlink_target)
subprocess.check_call([ponyd_path, 'update-devtools'])

0 comments on commit 4290b66

Please sign in to comment.