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 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 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