How to Modify¶
Rebuild Process¶
jpy’s source distribution directory layout uses the Maven common directory structure.
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 bysetup.py
.src/main/c
- C source files for the jpy Python APIsrc/test/python
- Python API test casessrc/main/java
- Java source files for the jpy Java APIsrc/test/java
- Java API test cases
After changing any source code just run setup again as indicated in the Build from Sources 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