.. note::
    These instrctions are a modified version of the
    `CPython devguide <http://docs.python.org/devguide/>`_

===============
Getting Started
===============

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.

OpenHatch also has a great `setup guide`_ for Python for people who are
completely new to contributing to open source.

.. _setup guide: https://openhatch.org/wiki/Contributing_to_Python


.. _setup:

Getting Set Up
==============


Version Control Setup
---------------------

Jython is developed using `Mercurial <http://hg-scm.org/>`_. 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 <http://tortoisehg.org/>`_ graphical client.


.. _checkout:

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 Jython 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.)

Patches for the documentation can be made from the same repository; see
:ref:`documenting`.

.. _compiling:

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.

.. _issue tracker: http://bugs.jython.org

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

     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.