Build a free-form project with sf3jswing-jigaxtended

Prerequisites

If you want to go through this short summary, we strongly recommend to have a sample knowledge of the POSIX commands, JDK 1.5 or any higher, and compiling Java applications with the Ant tool (build.xml).

System Requirements

Windows configuration

AMD or Intel 32 or 64 bits processors Microsoft Windows XP/Vista/7/8 or some more recent edition of the OS Java JDK 1.5 (1.6 or above is recommended)

Mac configuration

Intel (32 or 64 bits it doesn't matter) processors Mac OS X 10.5 (Leopard) or later Mac OS X includes the JDK by default (1.5 with Leopard, where 1.6 is on Snow Leopard and 1.7 on Lion) [edit]Linux configuration AMD64 or i386 processors: Some Linux OpenSuse or Ubuntu distribution (other builds are untested). The latest JDK package (or manually with correct PATH) must be installed

Additional requirements

Latest graphics drivers for AMD, Intel, Nvidia or any OpenGL capable devices. The Open JDK or any other open Java Development Kit may be compatible with the JigaXtended projects. All commands can be run from the command line (DOS or BASH). Android, iOS and other mobile devices are not supported.

Download and extract jigaxtended

Get the stable version

download the sf3jswing-jigaxtended release 4.3.0 or higher download the latest sf3jswing-jxakernel release 1.1.2+ choose a folder where you have all read&write permissions extract sf3jswing packages there you should have in the same folder : - sf3jswing-jigaxtended-4.3.0/ build.xml among other files - sf3jswing-jxakernel-1.1.2/ build.xml among other files

To get the most recent version

Read about how to download from the git repository

Create a public Code Signing Certificate Using the keytool

(Link to Oracle : https://docs.oracle.com/javase/tutorial/security/toolsign/step3.html)

The file build-jars.xml contains the following first lines :

#!shell

<property name="username" value="b23prodtm"/>
.="keystore" location="../.keystore"/>
.="keystore-type" value="jks"/>
.="storepass" value="password"/>
Something went wrong with the .keystore file that had to be found at two parent folders upside of your project. Run the Keytool of the JDK from the two-up parent folder "../../" :
:\>keytool 
(to see if it is available, if not, you must set up the JDK properly again (easy), or adjust you PATH settings)
Then use the Keytool to choose an alias/password (in that case you have to change the build-jars.xml properties)
:\>keytool -anycommand -keystore .keystore
Run
:\>keytool -storepasswd -keystore .keystore -new yourpassword 
to change the password to yourpassword
:\>keytool -anycommand -keystore .keystore -list
You should see b23prodtm (SHA1) : TH:E:KE:Y:..

This solves any "jarsigner error: java.lang.RuntimeException" .

You may experience problem with the Code Signing Certificate if you are using various .keystore's among your machines. Please make copy of the .keystore you created to ensure the same key pair is used to sign your .jars !

Compile the kernel library with ant

browse to sf3jswing-jxakernel folder

#!shell

cd sf3jswing-jxakernel-1.1.2

run the ant task update-template

if you cannot find the ant command, maybe Ant is not installed (especially on Linux systems). On Windows, it is packed with the IDE.

#!shell

ant -f ...\sf3jswing-jxakernel update-template
clean:
Deleting directory ...\sf3jswing-git\sf3jswing-jxakernel\bin
Deleting directory ...\sf3jswing-jxakernel\dist\Windows
compile:
Created dir: ...\sf3jswing-jxakernel\bin
Compiling 233 source files to ...\sf3jswing-jxakernel\bin
Note: Some input files use unchecked or unsafe operations.
Note: Recompile with -Xlint:unchecked for details.
filterLicenseFiles:
build-jar:
Created dir: ...sf3jswing-git\sf3jswing-jxakernel\dist\Windows\application
Created dir: ...\sf3jswing-jxakernel\dist\Windows\unsigned
Copying 1 file to...sf3jswing-jxakernel\resources\properties\Windows\x86\net\sf\jiga\xtended\kernel
Copying 1 file to ...sf3jswing-jxakernel
Building jar: ...sf3jswing-jxakernel\dist\Windows\unsigned\sf3jswing-jxakernel-Windows-x86.jar
checkforkey:
genkey:
jar:
Signing JAR:...sf3jswing-jxakernel\dist\Windows\unsigned\sf3jswing-jxakernel-Windows-x86.jar to ...sf3jswing-jxakernel\dist\Windows\application\sf3jswing-jxakernel-Windows-x86_signed.jar as b23prodtm
jar signed.

Warning: 
No -tsa or -tsacert is provided and this jar is not timestamped. Without a timestamp, users may not be able to validate this jar after the signer certificate's expiration date... or after any future revocation date.
DO-lib:
Created dir: ...\sf3jswing-jxakernel\dist\Windows\unsigned\lib
Building jar: ...\sf3jswing-jxakernel\dist\Windows\unsigned\lib\lib-sf3jswing-jxakernel-Windows-x86.jar
update-template:
_update-template-task:
Copying 1 file to ...sf3jswing-jigaxtended\lib\Windows\x86
_update-template-task:
Copying 1 file to ...sf3jswing-jxatest-unit\lib\Windows\x86
_update-template-task:
Copying 1 file to ...sf3jswing-imagemulticonverter-ant\lib\Windows\x86
_update-template-task:
Copying 1 file to ./../sf3jswing-imcbrowser\lib\Windows\x86
_update-template-task:
Copying 1 file to ./../es-sdk-jdk-binding\lib\Windows\x86
_update-template-task:
Copying 1 file to .../sf3jswing-git\sf3jswing-animsbrowser-ant\lib\Windows\x86
_update-template-task:
Copying 1 file to .../sf3jswing-git\sf3jswing-thegame-ant\lib\Windows\x86
BUILD SUCCESSFUL (total time: 26 seconds)

Open the sf3jswing-jigaxtended project folder (If you only want to use the JXAKernel, this section may not be helpful)

Now that the kernel is linked (copied into lib/osfamily/ folder), you can configure and compile sf3jswing-jigaxtended API.

Edit build-YOUROS-YOURARCH.xml. (If there are no additional native libraries .dll, .so, .dylib, skip this step)

Section below EXTENSIONS FILES AND *** NATIVE INSTALLER *** CONFIGURE HERE THE EXTENSIONS INSTALLER (USEFUL ON OPERATING SYSTEM RUNNING THE PLUGIN V. 1 (E.G. MAC OS X AND JAVA 5, OR SAFARI ON WINDOWS)

you must specify the location on the web where your -might- upload the sf3jswing-jigaxtended-ext-..jar's you must specify ALL native libraries that you want the kernel to install before to launch your JApplet-or-JFrame application copy the necessary natives in the resources/properties/YOUROS/YOURARCH/natives/ folder as they will be merged into the file sf3jswing-jigaxtended-YOUROS-YOURARCH-ext-native..jar.

If you edit sf3jswing-jigaxtended build-xml files, it will update all distributed .jars. Edit your own generated (see below) JXA project build-xml files to perform single project specific distributed .jars.

Locating 64 bits natives for the Windows platform

Running on an 64 bits windows even with the 32 bits JDK (e.g. Java Chrome Plugin for Windows only) implies that 64 bits native libraries must be loaded on the system. Therefore 64 bits native libraries like "jinput-dx8_64.dll" must be found in the project/resources/properties/Windows/all/natives and not ../Windows/amd64/natives. This is because a 32 bits compiler will not look into amd64 folder to add the natives to the .jar.

This issue does not involve Mac OS and other Unix platforms which cannot run 32 bits JDK/JVM on 64 bits machines.

Configure template/build-extended-template.xml (This provides the possibility to perform "automatic update" to your own project folders)

           EITHER IF YOU WANT A NEW PROJECT

Section below

           CREATE NEW JXA PROJECT (THAT MAY BE A FRAME APPLICATION OR AN APPLET)
           THIS WILL OUTPUT TO THE PARENT FOLDER OF YOUR COPY OF JIGAXTENDED PROJECT

#!xml
  <property name="new.project.template.name" value="a-new-project"/>

           EDIT HERE (see above) WITH THE NEW PROJECT NAME YOU WANT
           and use build.xml or build-YOUROS-YOURARCH.xml (no matter 
           if you run another OS or arch) to run DO-new-jxa-project

OR Section below UPDATE EXTERNAL EXISTING JXA PROJECT(S) or YOUR OWN PROJECT THAT WANTS TO USE JIGAXTENDED.

           EDIT HERE THE FOREACH LIST TO
           DO AUTOMATICALLY COPY THE EXTENSIONS.JARS
           INTO THE APPROPRIATE FOLDERS LOCATED IN THE LIST

#!xml

           <property name="target-path" location=".."/>
           <target name="update-template" depends="DO-jar-extension" description="Will perform build of the extension and update the targeted template projects">

LIST HERE THE PROJECT NAMES YOU ARE UPDATING THEY MUST BE LOCATED AT THE PARENT FOLDER OF YOUR COPY OF JIGAXTENDED PROJECT

#!xml
               <foreach 

                            list="some-projects,separated-by-commas-and,no-space" 
                            target="_update-template-task"
                            param="template-project.name">
                            </foreach>
             </target>

and use build.xml or build-YOUROS-YOURARCH.xml (no matter if you run another OS or arch) to run update-template

Open a new "free-form project" (e.g. in Netbeans) or Your own project

You might edit the src/all/jxa/ package to begin with a new JXA Free-Form Project (generated with build-extended-template.xml).

Configure the project for the IDE

Classpath .jar's

It may be useful to configure the editor project Java classpath to look into resources/YOUROS/YOURARCH/*ext_signed.jar files and lib/YOUROS/YOURARCH/lib-sf3jswing-jxakernel-..jar.

Resources files (natives, .properties list, animations, sounds, etc.)

You can make the whole resources tree be visible in the project navigator by adding the resources/properties/ folder to the IDE project Java packages folders set.

For native libraries which you may want to add in for a specific project folder, refer to the section above about sf3jswing-jigaxtended. The configuration for a free-form JXA project is the same within its own folders structure and build files.

Readme and License files locations and edition

Open the project base README and HOWTO text files for more information about build.xml's in JXA Free-form Projects. Open and edit resources/all/LICENSE and resources/all/NOTICE to include your own copyright. see that a tag of annotations like Copyright @PROJECTYEARS@ @COMPANYNAME@ includes your company name for the values you have specified in the build-jars.xml file. Run task DO-src-pack to obtain the distributing tarball (GZip compressed) and the final license files.

JXA Free-Form projects "built-in" ant tasks

build.xml or build-osfamily-arch.xml

If you're familiar with ant, then you can skip to the list of tasks available to jxa free-form projects. When a JXA Free-form project is made by DO-new-jxa-project, the ant builder makes a project file structure that entirely relies on a set of XML files. Those XML files are the ANT build configuration files. As in any other configuration files, there are properties set to values and targets defining tasks that the ant tool can execute. On the command line, ant is very easy to invoke :

#!shell

ant jar

or

ant -f myProject/build.xml DO-clean-root

for more infos see ant manual; also, there is a extension pack for ant called [ant-contrib.sourceforge.net/|ant-contrib] (it provides easy access to script with ant targets). With the help of an IDE you can see all tasks available when browsing around any of the build.xml's. See Running ANT targets from NetBeans IDE for instance !

list of built-in targets

compile

compiles all source files (src/all + src/osfamily) into binaries (bin/)

jar

packs all binaries (bin/*.class) and resources into .jar zipped packages (dist/osfamily/unsigned) before to sign them (dist/osfamily/applet).

run(*)

runs the .jar with the AntFrame you specified as the -antframe argument in the build-os-arch.xml application.run.params.

run-applet(*)

runs the .jar with the AntApplet in Appletviewer you specified as the -antapplet argument in the build-os-arch.xml applet.run.params. (notice : if you need access to some more Security Permissions, edit the JavaSecurityPolicy file !)

clean

erases all files in dist/osfamily/ and bin/ folders.

DO-clean-root

erases all files in dist/ folder (all os builds)

javadoc

performs a validation of /* documentation in .java files / and builds the JavaDoc for the current project (dist/doc/)

DO-src-pack

gathers all files excepting dist/ and bin/ folders to compress them into a tarball (dist/tarball) there are also some files added aside the tarball : .spec .changes .dsc debian., these files are used by the RPM-DEB package builders (e.g. OpenSuSE.org Build Service).

install

platform specific bundle linux users will have the project unsigned jar's copied into /usr/share/games/nameoftheproject and an executable into /usr/games named as the project name. NOTICE : the project name MUST BE low-capitalized (debian rules) in order to be used by the linux systems. mac os users will have a nameoftheproject.app application bundle built in the dist/Mac/applet folder. windows users will have a nameoftheproject.exe and nameoftheproject_debug.exe in the dist/Windows/applet folder that MUST STAY IN THE SAME FOLDER AS THE JAR's to run properly (classpath issues).

update-template (available from the JIGAXtended project)

cleans, builds and copies *signed.jar and lib-sf3jswing-jxakernel-..jar to the corresponding operating system project resources and lib folders in the projects listed in sf3jswing-jigaxtended/template/build-extended-template.xml . Use it when you update the JIGAXtended API source code, resources or lib folder.

DO-lib (available from the JXA Kernel project)

cleans, builds the lib-sf3jswing-jxakernel-..jar (unsigned) into the sf3jswing-jxakernel/dist/../unsigned folder. Use it if you updated the sf3jswing-jxakernel sources, resources or lib folder. Then copy the dist/../unsigned/lib-..jar to the lib/yourOS/yourArch folder of your project or JIGAxtended lib/yourOS/yourArch for further updating the templates.

Test Units

sf3jswing-jxatest-unit

This is a JXA free-form project, that is made to test the whole JXA API engine (Swing UI, I/O processes, multi-threading, Open GL (through LWJGL),..) on targeted systems. It has TestAntFrame and TestAntApplet to make test on both JFrame and JApplet release of Free-Form projects. It has been built with the DO-new-jxa-project sf3jswing-jigaxtended's target. The RenderingScene should run on everw compatible system.

(*) NOTES

IMPORTANT NOTE about Applets

If you run a JFCApplet locally , you must manually enable the jxa.localApplet property (-Djxa.localApplet=true), otherwise you may experience some Class cast error with serialization.

JXA Debugging System Properties

Edit build-jars.xml below target for the corresponding system family : E.g. for the target "run" :

#!xml

<target name="run" .>
<exec . os. >
<arg line="-Dorg.lwjgl.util.Debug=true"/><!-- LWJGL debug //-->
            <arg line="-Djxa.debugSys=true"/><!-- jxa kernel //-->
            <arg line="-Djxa.debug=true"/><!-- global jxa api debug (casual info)//-->
            <arg line="-Djxa.debugRender=true"/><!-- rendering (sprite, models,anims,..) //-->
            <arg line="-Djxa.debugSPM=true"/> <!-- cache debug de/serialization //-->
            <arg line="-Djxa.debugECL=true"/> <!-- Extensions classloader debug //-->

</exec>
</target>

E.g. for the target run-applet it uses the -J-D options, for AppletViewer is running :

#!xml

<target name="run-applet" .>
<exec . os. >

<arg line="-J-Dorg.lwjgl.util.Debug=true"/>
<!-- LWJGL debug //-->

            <arg line="-J-Djxa.debugSys=true"/>
<!-- jxa kernel : USE IT FOR ANY ISSUE THAT CAN OCCUR AT THE FIRST STEPS OF LAUNCHING YOUR APP//-->

            <arg line="-J-Djxa.debug=true"/>
<!-- global jxa api debug (casual info and deep field dbugers)//-->

            <arg line="-J-Djxa.debugRender=true"/>
<!-- rendering (sprite, models,anims,..) (USE IT TO FIX UNWANTED GRAPHICS ERRORS)//-->

            <arg line="-J-Djxa.debugSPM=true"/>
 <!-- cache debug de/serialization (USE IT TO FIX JAR SPRITES RESOURCES LOADING ISSUES)//-->

            <arg line="-J-Djxa.debugECL=true"/> 
<!-- Extensions classloader debug (USE IT TO FIX CLASSPATH ISSUES) //-->
<exec>
</target>

Applets on the web also read parameters from the yourProjectName.html file :

#!html
<APPLET archive="api/@PROJECTOSKERNELJAR@" code="@PROJECTAPPLETMAIN@" width=@PROJECTAPPLETWIDTH@ height=@PROJECTAPPLETHEIGHT@>
            Your browser does not support Java, so nothing is displayed.<!-- VOID DOUBLE RESOURCE LOADING, NOT USED WITH EXTENSION MECHANISM param name="jnlp_href" value="@PROJECTAPPLETJNLPHREF@"/-->

            <param name="jxa.debug" value="true"/>
            <param name="jxa.debugSys" value="true"/>
            <param name="jxa.debugOps" value="true"/>
            <param name="jxa.debugRender" value="true"/>
            <param name="jxa.debugVoid" value="false"/> <!-- some of deleted lines of debugging //-->
            <param name="jxa.debugSPM" value="true"/>
            <param name="jxa.debugECL" value="true"/>
            <param name="antapplet" value="@PROJECTAPPLETANTAPPLET@"/> <!-- edit build-yourOS-arch.xml //-->
            <param name="applet.classpath" value="@PROJECTAPPLETCLASSPATH@"/> <!-- edit build-yourOS-arch.xml //-->
            <param name="antargs" value="@PROJECTAPPLETARGS@"/> <!-- edit build-yourOS-arch.xml //-->
            <PARAM name="java_arguments" value="@PROJECTAPPLETARGS@"/> <!-- edit build-yourOS-arch.xml //-->
            <param name="separate_jvm" value="true"/>

Developing JXA projects with Netbeans

About code error checking and completion

Netbeans provides a powerful code error checking and completion integrated tool, which is worth to get used to it. It's fast and pretty easy to detect source paths, even if you have multiple project instances opened at the same time. For example, by editing the project properties / source classpaths option panel, you will make the Java Editor look into each of the specified .jar for known classes that your project imports in .java files. You can also edit the Tools / Java Platforms option panel to add JDK or any other Sources paths to the Java IDE. E.g. you want to specify a global API Documentation folder, that helps you find the correct API function when you type in new lines of code. Note : sometimes the Java Editor doesn't refresh its classpaths or even don't find the API you have specified previously. To force a cache refresh, Close the project, restart Netbeans and re-open the project from the recently used project File menu.

Activating Netbeans Debugger within projects

Netbeans IDE provides a powerful debugger that can help developers to find/solve many bugs and issues. It's able to recognize breakpoints, VM Heap usage, variable monitoring, etc.

But you'll have to make some changes in the JXA free-form project ide-file-targets.xml that is generated when you first run the debug interface [press Ctrl+F5 in Netbeans or try to run once the debug targets]. Set output classpath to target the bin/ project folder. Here's a sample of the sf3jswing-jxatest-unit project file : rename the first line project name to the actual name for your project (without -IDE), as in build-jars.xml :

#!xml


<project basedir=".." name="yourProjectName">

the following imports JXA build files;

#!xml

<import file="../build-${os.name}-${os.arch}.xml"/>
    <import file="../build-jars.xml"/>

add clean and jar dependencies to the target, so that debugging ensures a fresh revision to be run :

#!xml
<target depends="-jdk-init, clean, jar" name="debug-nb"> 
<path id="cp">
            <!-- TODO configure the runtime classpath for your project here: -->
            <fileset dir="${dist}"><include name="**/*.jar"/></fileset>
        </path> 

this reads jar files from the JXA project dist/os.name folder (note the ${dist} ant-variable that was imported from build-${os.name}-${os.arch}.xml); and provide specific parameters here for your project to run in the debugger. Refer to the file build-jars.xml,<target name=run>, of your current running project for specific parameters.

#!xml
        <nbjpdastart addressproperty="jpda.address" name="sf3jswing-jxatest-unit" transport="dt_socket">
            <classpath refid="cp"/>
        </nbjpdastart>
        <!-- TODO configure the main class for your project here: -->
        <java dir="${dist}" classname="${company.project.os.application.run.main}" fork="true">
            <classpath refid="cp"/>
            <arg line="${company.project.os.application.run.args}"/>
            <jvmarg value="-ea"/>
            <jvmarg value="-Xdebug"/>
            <jvmarg value="-Xrunjdwp:transport=dt_socket,address=${jpda.address}"/>      
        </java>

For a JXA project that uses the AntApplet as main class you must copy the classpath parameter since the HTML file is not read from java executable for debugging and it looks like the following : Refer to the file build-jars.xml,<target name=run-applet>, of your current running project and the file yourProject.html file for specific parameters. Thanks to Netbeans for this tool.

Using Eclipse formatted code

If you are working in team on an Eclipse project, you may find it useful to install the Eclipse Java Code Formatter. Open Netbeans, go to the Tools > Plugins > Available Plugins to install this module.

FAQ Git :

resolving conflicts / rebase / commit between branches

How to recover from an unchecked remote repository, which you have made changes into and want to merge and commit with the latest remote revisions ? It is based on the following steps, (either use Github or Netbeans) :

"The local "master" branch is now being in conflict with the remote "origin/master" and I cannot commit changes..."

• (GitHub) Create a new local branch for backup, e.g. "backupCommit
• Pull changes from the remote, it will result in conflicts, which you can immediately merge and resolve (Netbeans) or accept to discard your local changes (GitHub) to resolve them.
• (Netbeans) Teams > Remote > Branch/Tag > Merge Revisions > backupCommit to HEAD or (GitHub) Merge the branch with the local "HEAD".
• This is what will do the final trick : Rebase (Netbeans > Teams > Git > Rebase > master to origin/master) or (GitHub) git merge-base master origin/master .
• Now you can commit your master to the remote origin/master !