Source

jython-docs/devguide / setup.rst

Full commit

Getting Set Up

These instructions cover how to get a working copy of the source code and a compiled version of the Jython interpreter (Jython is the version of Python available from http://www.jython.org/). It also gives an overview of the directory structure of the Jython source code.

Version Control Setup

CPython is developed using Mercurial. The Mercurial command line program is named hg; this is also used to refer to Mercurial itself. Mercurial is easily available for common Unix systems by way of the standard package manager; under Windows, you might want to use the TortoiseHg graphical client.

Getting the Source Code

One should always work from a working copy of the Jython source code. While it may be tempting to work from the copy of Jython you already have installed on your machine, it is very likely that you will be working from out-of-date code as the Jython core developers are constantly updating and fixing things in their :abbr:`VCS (version control system)`. It also means you will have better tool support through the VCS as it will provide a diff tool, etc.

To get a working copy of the :ref:`in-development <indevbranch>` branch of Jython (core developers use a different URL as outlined in :ref:`coredev`), run:

hg clone http://hg.python.org/jython

If you want a working copy of an already-released version of Jython, i.e., a version in :ref:`maintenance mode <maintbranch>`, you can update your working copy. For instance, to update your working copy to Jython 2.5, do:

hg update 2.5

You will need to re-compile Jython when you do such an update.

Do note that CPython will notice that it is being run from a working copy. This means that if you edit Jython's source code in your working copy, changes to Python code will be picked up by the interpreter for immediate use and testing. (If you change Java code, you will need to recompile the affected files as described below.)

Compiling

Compiling Jython is fairly simple, from the top level of a source checkout do:

ant

Build dependencies

The core Jython interpreter depends on a number of jars. TODO: jars TODO: jython dev build

Once Jython is done building you will then have a working build that can be run in-place; ./dist/bin/jython There is normally no need to install your built copy of Jython! The interpreter will realize where it is being run from and thus use the files found in the working copy.

Editors and Tools

Python is used widely enough that practically all code editors have some form of support for writing Python code. Various coding tools also include Python support.

Jython specific support is less common but supported in several IDEs. Many of the core developers do pretty well with Emacs or Vim :)

TODO: Eclipse

TODO: Netbeans

For editors and tools which the core developers have felt some special comment is needed for coding in Python, see :ref:`resources`.

Directory Structure

There are several top-level directories in the Jython source tree. Knowing what each one is meant to hold will help you find where a certain piece of functionality is implemented. Do realize, though, there are always exceptions to every rule.

Demo
Outdated Jython demo code. TODO: fix this to make it current.
Doc

Outdated Jython website docs.

TODO: Jython should put our fork of the CPython directory (the official documentation) in an official hg repo in the python.org infrastructure. The official documentation. This is what http://jython.org/docs uses. To build the docs, see TODO.

Lib
The part of the standard library implemented in pure Python. A future goal is to do a way with this and exclusively use the CPython Lib with Jython versions checked in there.
Misc
Things that do not belong elsewhere. Typically this is varying kinds of developer-specific tools and documentation.
ast

Code related to the parser. The definition of the AST nodes is also kept here.

TODO: It may be a good idea to rename this directory "Parser" to match CPython.

bugtests

Outdated framework for testing Jython.

Todo: tests that remain here should be ported to Lib/tests/

extlibs
External Java dependencies for Jython.
grammar
ANTLR source for building Jython's grammar.
maven
Source for including Jython in Maven.
src
The part of the Jython interpreter that is implemented in Java.
tests
Tests for Jython implemented in Java.
Tools
Various tools that are (or have been) used to maintain Jython.