#############
How to Modify
#############

===============
Rebuild Process
===============

jpy's source distribution directory layout uses the `Maven common directory structure <http://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html>`_.

* ``setup.py`` - Python build/installation script, will compile Python and Java sources, install the libraries and run all unit-level tests.
* ``pom.xml`` - Maven project file to build the Java sources. Called by ``setup.py``.
* ``src/main/c`` - C source files for the jpy Python API
* ``src/test/python`` - Python API test cases
* ``src/main/java`` - Java source files for the jpy Java API
* ``src/test/java`` - Java API test cases


After changing any source code just run setup again as indicated in the :ref:`build` process.


After changing signatures of native methods in ``src/main/java/org/jpy/PyLib.java``, you need to compile the Java classes
and regenerate the C headers for the ``PyLib`` class using Maven::

    mvn compile
    javah -d src/main/c/jni -v -classpath target/classes org.jpy.PyLib

Then always adapt changes ``org_jpy_PyLib.c`` according to newly generated ``org_jpy_PyLib.h`` and ``org_jpy_PyLib_Diag.h``.
Files are found in ``src/main/c/jni/``. Then run setup again as indicated above.

=======================
C Programming Guideline
=======================

* Follow style used in Python itself
* Python type global variable names: `J<type>_Type`
* Python type instance structs: `JPy_J<type>`
* Python function decl for a type: `J<type>_<FunctionName>(JNIEnv* jenv, JPy_J<type>* <type>, ...)`
* The pointer is always the first parameter, only type slots obtain their `jenv` from `JPy_GetJEnv()`
* Python slots function for a type: `J<type>_<slot_name>(JNIEnv* jenv, JPy_J<type>* self, ...)`
* Usually functions shall indicate errors by returning NULL or -1 on error.
  Callers can expect that the PyErr_SetError has been set correctly and thus simply
  return NULL or -1 again.
  Exception: very simple functions, e.g. `JObj_Check()`, can go without error status indication.
* Naming conventions:

    * jpy_jtype.h/c - The Java Meta-Type
        * JPy_JType type
        * JType_xxx() functions
    * jpy_jobj.h/c  - The Java Object Wrapper
        * JPy_JObj type
        * JObj_xxx() functions
    * jpy_jmethod.h/c - The Java Method Wrapper
        * JPy_JMethod type
        * JPy_JOverloadedMethod type
        * JMethod_xxx() functions
        * JOverloadedMethod_xxx() functions
    * jpy_jfield.h/c - The Java Field Wrapper
        * JPy_JField type
        * JField_xxx() functions
    * jpy_conv.h/c - Conversion of Python objects from/to Java values
        * JPy_From<JType> functions / JPy_FROM_<JTYPE> macros create Python objects (new references!) from Java types
        * JPy_As<JType> functions / JPy_AS_<JTYPE> macros convert from Python objects to Java types
    * jpy_diag.h/c - Control of outputting diagnostic info
        * JPy_Diag type
        * JPy_DIAG_F_<name> macros
        * JPy_DIAG_PRINT(flags, format, ...) macros
    * jpy_module.h/c - The 'jpy' module definition
        * JPy_xxx() functions
    * jni/org_jpy_PyLib.h - generated by javah from PyLib.java
    * jni/org_jpy_PyLib_Diag.h - generated by javah from PyLib.java
    * jni/org_jpy_PyLib.c - native implementations from PyLib.java

