Notes about regenerating *Derived.java and jython.exe

Author: jeff5

setup_jy.rst

@@ -4,9 +4,11 @@
 Getting Started
 ===============
 
+.. highlight:: console
+
 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
+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 has a partly-relevant `setup guide`_ for CPython for people who are
@@ -72,13 +74,13 @@ 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
+   $ 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
+   $ hg update 2.5
 
 GitHub
 ^^^^^^
@@ -100,7 +102,20 @@ Compiling
 
 Compiling Jython is fairly simple, from the top level of a source checkout do::
 
-    ant
+   $ ant
+
+Each time you issue this command, ``ant``  builds incrementally,
+by compiling those Java source files that have changed,
+and copying the Python and other files that have changed
+to the :file:`dist` directory.
+Several other useful targets may be named to ``ant``,
+in particular, ``ant clean`` will delete the :file:`dist` and :file:`build`
+directories so that a subsequent plain ``ant`` will rebuild everything.
+The command::
+
+   $ ant -p
+
+lists the top-level targets.
 
 .. _build-dependencies-jy:
 
@@ -204,3 +219,67 @@ every rule.
 ``Tools``
    Various tools that are (or have been) used to maintain Jython.
 
+
+
+Manually regenerated files
+==========================
+
+Some files are programmatically generated, but not by ``ant``,
+nor destroyed by ``ant clean``.
+These must be regenerated by the developer when necessary,
+and new versions checked-in like source files.
+
+Derived Java source
+-------------------
+
+Some Java source that supports subclassing of built-in types
+is generated using Python scripts.
+These files need to be refreshed only when the signatures of exposed methods
+of the corresponding types change.
+A new one must be created when a new type is added.
+Notes about this are currently on the Jython Wiki at
+`Generating the *Derived classes <https://wiki.python.org/jython/GeneratedDerivedClasses>`_.
+
+The launcher ``jython.exe``
+---------------------------
+
+.. highlight:: ps1con
+
+:file:`src/shell/jython.exe` is the Windows Jython launcher.
+It is copied during the ``ant`` build to :file:`dist/bin`.
+However, it is derived from :file:`src/shell/jython.py` using PyInstaller_
+by the following process.
+
+If it is not already installed, install ``virtualenv``
+with the command ``pip install virtualenv``.
+In any convenient working directory, create a virtual environment, activate it,
+and install ``PyInstaller``::
+
+   > virtualenv venv
+   New python executable in ... venv\Scripts\python.exe
+   Installing setuptools, pip, wheel...done.
+   > .\venv\Scripts\activate
+   (venv) > pip install pyinstaller
+   Collecting pyinstaller
+   ...
+   Installing collected packages: future, pypiwin32, ..., pyinstaller
+   Successfully installed ... pyinstaller-3.3
+
+The above set-up need only be performed once.
+
+Copy :file:`src/shell/jython.py` to this working directory.
+Use ``PyInstaller`` to create a single-file executable,
+and copy that back to :file:`src/shell`::
+
+   (venv) > copy <checkoutdir>\src\shell\jython.py .
+   (venv) > pyinstaller --onefile jython.py
+   ...
+   (venv) > copy .\dist\jython.exe <checkoutdir>\src\shell
+
+Above, ``<checkoutdir>`` stands for the root directory of the Jython source.
+You *could* do all this in the source tree at :file:`src/shell`,
+but the virtual environment and ``PyInstaller`` leave a lot of
+working material behind, so it is best done elsewhere.
+
+.. _PyInstaller: http://www.pyinstaller.org
+