4. setup.py extensions by setupjavax — setupjavax documentation

# 4. setup.py extensions by setupjavax

The setupjavax provides the following extensions for the standard setup.py of the setuptools / distutils. See EXAMPLES for required integration steps, check integration with:

>     python setup.py –help-commands.

Use new commands and options:

- setup.py extension commands:

  >     build_java      build_jy

- setup.py common global options:

  >     –sdk
  >     –no-install-requires    –offline
  >     –help-setupjavax

## 4.1. SYNOPSIS

    setup.py [Global-OPTIONS] [COMMANDS-with-context-OPTIONS]

## 4.2. OPTIONS

### 4.2.1. –sdk

Supports a separate dependency list for the build and packaging environment. The following informal convention has to be implemented within the file setup.py.

>     __sdk = False
>     """Set by the option "--sdk". Controls the installation environment."""

>     if '--sdk' in sys.argv:
>         _sdk = True
>         sys.argv.remove('--sdk')

>     _packages_sdk = find_packages(include=['setuplib'] )  # your development packages
>     """Python packages to be installed."""

>     if __sdk: # pragma: no cover
>         _install_requires.extend(
>             [
>                 'sphinx >= 1.4',
>                 'epydoc >= 3.0',
>             ]
>         )

>         _packages = _packages_sdk

For an example refer to setup.py of setuplib.

### 4.2.2. –no-install-requires

Suppresses installation dependency checks, requires appropriate PYTHONPATH. The following informal convention has to be implemented within the file setup.py.

>     __no_install_requires = False

>     if '--no-install-requires' in sys.argv:
>         __no_install_requires = True
>         sys.argv.remove('--no-install-requires')

>     if __no_install_requires:
>         print("#")
>         print("# Changed to offline mode, ignore install dependencies completely.")
>         print("# Requires appropriate PYTHONPATH.")
>         print("# Ignored dependencies are:")
>         print("#")
>         for ir in _install_requires:
>             print("#   "+str(ir))
>         print("#")
>         _install_requires=[]

For an example refer to setup.py of setuplib.

### 4.2.3. –offline

Sets online dependencies to offline, or ignores online dependencies. The following informal convention has to be implemented within the file setup.py.

>     __offline = False

>     if '--offline' in sys.argv:
>         __offline = True
>         __no_install_requires = True
>         sys.argv.remove('--offline')

For an example refer to setup.py of setuplib.

### 4.2.4. –help-commands

The option ‘–help-commands’ itself is not part of the setuplib, but it lists all successfull integrated extension commands. Thus the current extension commands has to be visible for validation.

### 4.2.5. –help-setuplib

Special help for setuplib.

For an example refer to setup.py of setuplib.

## 4.3. COMMANDS

### 4.3.1. build_java

Compiles java modules for ‘Jython’ and copies them into the build subtree. The standard command ‘build_py’ has to be called extra.

Warning

The mix of Python and Java modules within the same directory for the runtime directories in particular in combination with an __init__.py / __init__.pyc is in case of Jython error prone.

This is due to the required pre-scan of all packages within the startup initialization prologue by Jython. Which is madatorily required in order to support Python reflection for the Java packages. Thus seemingly the package path resolution prioritizes the Python resolution and therefore hides Java modules located within the same directory path. Once these are split into a seperate directory path anything is fine.

It seems to work in case of the default package within the global namespace, but this is due to the in any case required split not further thoroughly investigated.

Creates for example in case of platformids [platformids] by default from the source-tree:

>     platformids
>     └── jy
>        └── dist
>            └── nt
>                ├── Advapi32GetCurrentVersion.java
>                ├── Kernel32GetProductInfo.java
>                └── ReadCurrentVersionWinPrefs.java

the build tree with binaries only:

>     build/
>     └── lib
>         └── platformids
>             └── jy
>                 └── dist
>                     └── nt
>                         ├── Advapi32GetCurrentVersion.class
>                         ├── Kernel32GetProductInfo.class
>                         └── ReadCurrentVersionWinPrefs.class

The command supports a subset of the javac and jython options as convenience options. For a complete set the commands has to be called direct.

#### 4.3.1.1. –cp=

The classpath for the Java compiler.

Input:

>     setup.py build_java --cp=<classpath>

Java compiler call:

>     javac -cp <classpath> -jar /path/to/jython/jython.jar ...

The compilation of packages with platform support may for example require:

>     javac -cp %cd%;c:\jna\jna.jar;c:\jna\jna-platform.jar;c:\jna\win32-x86-64.jar -jar c:\jython\jython.jar ...

>     javac -cp ${PWD}:/opt/jna/jna.jar:/opt/jna/jna-platform.jar:/opt/jna/win32-x86-64.jar -jar /opt/jython/jython.jar ...

#### 4.3.1.2. –deprecation

Output source locations where deprecated APIs are used.

Input:

>     setup.py build_java --deprecation

Java compiler call:

>     javac -deprecation -jar /path/to/jython/jython.jar ...

#### 4.3.1.3. -g

Generates complete debugging information for java.

Input:

>     setup.py build_java -g

Java compiler call:

>     javac -g-all -jar /path/to/jython/jython.jar ...
>     javac -g     -jar /path/to/jython/jython.jar ...

#### 4.3.1.4. –jp=

The sys.path/classpath for Jython.

Input:

>     setup.py build_java --jp=<jp>

Java compiler call:

>     javac  -jar /path/to/jython/jython.jar -Dpython.path <jp>...  # see [Jython]

#### 4.3.1.5. –no-exec

Print only, do not execute.

>     javac --no-exec

#### 4.3.1.6. –nowarn

Generate no warnings.

Input:

>     setup.py build_java --nowarn

Java compiler call:

>     javac -nowarn  -jar /path/to/jython/jython.jar ...

#### 4.3.1.7. –source=

Provide source compatibility with specified release.

Input:

>     setup.py build_java --source=<release>

Java compiler call:

>     javac -source <release>  -jar /path/to/jython/jython.jar ...

#### 4.3.1.8. –src

Copies sources, default is the class files only:

>     setup.py build_docx --src

Creates for example in case of platformids [platformids] from the source-tree:

>     platformids
>     └── jy
>        └── dist
>            └── nt
>                ├── Advapi32GetCurrentVersion.java
>                ├── Kernel32GetProductInfo.java
>                └── ReadCurrentVersionWinPrefs.java

the build tree with binaries and included sources:

> >     build/
> >     └── lib
> >         └── platformids
> >             └── jy
> >                 └── dist
> >                     └── nt
> >                         ├── Advapi32GetCurrentVersion.class
> >                         ├── Advapi32GetCurrentVersion.java
> >                         ├── Kernel32GetProductInfo.class
> >                         ├── Kernel32GetProductInfo.java
> >                         ├── ReadCurrentVersionWinPrefs.class
> >                         └── ReadCurrentVersionWinPrefs.java

#### 4.3.1.9. –target=

Generate class files for specific VM version.

Input:

>     setup.py build_java --target=<release>

Java compiler call:

>     javac -target <release> -jar /path/to/jython/jython.jar ...

#### 4.3.1.10. –verbose

Displays extra information

Input:

>     setup.py build_java --verbose

Java compiler call:

>     javac -verbose -jar /path/to/jython/jython.jar ...

#### 4.3.1.11. –werror

Terminate compilation if warnings occur.

Input:

>     setup.py build_java --werror

Java compiler call:

>     javac -Werror -jar /path/to/jython/jython.jar ...

### 4.3.2. build_jy

Extends ‘build_py’ for compilation of Python and Java modules for Jython. Calls build_py and build_java, therefore provides a set of options for both.

> option | reference command |
> --- | --- | ---
> –build-lib= | build_py –build-lib | [setuptools]
> –compile | build_py –compile | [setuptools]
> –cp= | build_java –cp |
> –deprecation | build_java –deprecation |
> –force= | build_py –force | [setuptools]
> –jp= | build_java –jp |
> –no-compile | build_py –no-compile | [setuptools]
> –no-exec | build_java –no-exec |
> –nowarn | build_java –nowarn |
> –optimize= | build_py –optimize | [setuptools]
> –source= | build_java –source |
> –target= | build_java –target |
> –verbose= | build_java –verbose |
> –werror= | build_java –werror |
> -g | build_java -g |

## 4.4. DESCRIPTION

The call interface ‘setuplib’ provides command line extensions for the command line call interface of setup.py.

The curent version supports extension commands, future versions will support extension-points.

## 4.5. EXAMPLES

0. Import in your setup.py for example:

   >     #
   >     # setup extension modules
   >     #
   >     from setuplib import usage
   >     from setuplib.build_java import BuildJava
   >     from setuplib.build_docx import BuildDocX
   >     from setuplib.install_docx import InstallDocX
   >     from setuplib.testx import TestX

   >     class build_docx(BuildDocX):
   >         def __init__(self, *args, **kargs):
   >             BuildDocX.__init__(self, *args, **kargs)
   >             self.name = 'setuplib'                      # your package name

   >     class install_docx(InstallDocX):
   >         def __init__(self, *args, **kargs):
   >             InstallDocX.__init__(self, *args, **kargs)
   >             self.name = 'setuplib'                      # your package name

   >     class build_java(BuildJava):
   >         def __init__(self, *args, **kargs):
   >             BuildJava.__init__(self, *args, **kargs)
   >             self.name = 'setuplib'                      # your package name

   >     class testx(TestX):
   >         def __init__(self, *args, **kargs):
   >             TestX.__init__(self, *args, **kargs)
   >             self.name = 'setuplib'                      # your package name

1. Hook them in e.g. as a command in your setup.py by:

   >     setup(
   >         cmdclass={                           # see [setuppy]
   >             'build_java': build_java,
   >             'build_docx': build_docx,
   >             'install_docx': install_docx,
   >             'testx': testx,
   >         },
   >         ...
   >     )

2. Use them from the command line call for example by:

   >     python setup.py –help-setuplib

   >     python setup.py --help-commands           # see [setuppy]

   >     python setup.py build_java --help

   >     python setup.py build_java

## 4.6. SEE ALSO

setup.py, setuplib, [setuptools], [distutils]

## 4.7. LICENSE

Artistic-License-2.0 + Forced-Fairplay-Constraints

## 4.8. COPYRIGHT

Copyright (C)2019 Arno-Can Uestuensoez @Ingenieurbuero Arno-Can Uestuensoez