From 771baa124d28c4825f16e6caeb32976f971a7226 Mon Sep 17 00:00:00 2001 From: Ana Gabriela Reyna Date: Wed, 20 Sep 2023 18:17:24 +0100 Subject: [PATCH] edited getting started and added AOT as a guide --- ...applet-runner.mdx => 03-applet-runner.mdx} | 2 +- .../03-getting-started/00-Java-app.md | 58 +++++++++ .../03-getting-started/01-Getting-Started.md | 123 ------------------ .../03-getting-started/01-Java-applet.mdx | 92 +++++++++++++ .../AOT-optimization.md} | 106 ++++++++++++--- src/content/docs/cheerpj2/index.md | 2 +- 6 files changed, 242 insertions(+), 141 deletions(-) rename src/content/docs/cheerpj2/{03-getting-started/applet-runner.mdx => 03-applet-runner.mdx} (97%) create mode 100644 src/content/docs/cheerpj2/03-getting-started/00-Java-app.md delete mode 100644 src/content/docs/cheerpj2/03-getting-started/01-Getting-Started.md create mode 100644 src/content/docs/cheerpj2/03-getting-started/01-Java-applet.mdx rename src/content/docs/cheerpj2/{03-getting-started/00-Tutorial.md => 04-guides/AOT-optimization.md} (54%) diff --git a/src/content/docs/cheerpj2/03-getting-started/applet-runner.mdx b/src/content/docs/cheerpj2/03-applet-runner.mdx similarity index 97% rename from src/content/docs/cheerpj2/03-getting-started/applet-runner.mdx rename to src/content/docs/cheerpj2/03-applet-runner.mdx index 1936e9fa..9ffca6f6 100644 --- a/src/content/docs/cheerpj2/03-getting-started/applet-runner.mdx +++ b/src/content/docs/cheerpj2/03-applet-runner.mdx @@ -3,7 +3,7 @@ title: CheerpJ Applet Runner subtitle: Run Java applets without installing Java --- -import LinkButton from "../../../../components/LinkButton.astro"; +import LinkButton from "../../../components/LinkButton.astro"; The CheerpJ Applet Runner is a browser extension that enables Java applets without requiring a local Java installation or to install deprecated plugins. diff --git a/src/content/docs/cheerpj2/03-getting-started/00-Java-app.md b/src/content/docs/cheerpj2/03-getting-started/00-Java-app.md new file mode 100644 index 00000000..cd4c8e6a --- /dev/null +++ b/src/content/docs/cheerpj2/03-getting-started/00-Java-app.md @@ -0,0 +1,58 @@ +--- +title: Run a Java Application +--- + +CheerpJ can run a Java application in the browser with little to no modifications. This page will help you getting started with CheerpJ and running your first Java application in the browser. + +**To get started you will need:** + +- Your java application file(s) +- An HTML file where your Java app will be wrapped +- A simple HTTP server to test your webpage locally + +## 1. Create a basic HTML file + +Let's start by creating a simplet HTML file like the following example. Please notice the CheerpJ runtime environment has been integrated. In this example we are assuming your HTML file and your .jar files are under the same directory. + +```html title="index.html" {6, 9-16} + + + + + CheerpJ test + + + + + +``` + +## 2. Host your page + +You can now serve this web page on a simple HTTP server, such as the http-server utility. + +```shell +npm install http-server +http-server [path] [options] +``` + +## What's going on? + +- CheerpJ loader is included from our cloud runtime as + ``. +- CheerpJ runtime environment is initilized by `cheerpjInit()`. +- `cheerpjCreateDisplay()` creates a graphical environment to contain all Java windows +- `cheerpjRunMain()` executes the `main` method of `ChangeThisToYourClassName`. The second parameter is a `:` separated list of `.jar` files where application classes can be found (the classpath). +- The `/app/` is a virtual file system mount point that reference the root of the web server this page is loaded from. + +## Further reading + +- [AOT optimization](/cheerpj2/guides/AOT-optimization) +- [Runtime API](http://localhost:3000/cheerpj2/reference/Runtime-API) diff --git a/src/content/docs/cheerpj2/03-getting-started/01-Getting-Started.md b/src/content/docs/cheerpj2/03-getting-started/01-Getting-Started.md deleted file mode 100644 index 7a26adf7..00000000 --- a/src/content/docs/cheerpj2/03-getting-started/01-Getting-Started.md +++ /dev/null @@ -1,123 +0,0 @@ ---- -title: Getting started ---- - -This page will help you getting started with CheerpJ and converting your first Java application to JavaScript in no time. - -To start, make sure to download the latest available version of CheerpJ [here](https://leaningtech.com/download-cheerpj/). Decompress the CheerpJ 2.3 archive anywhere, for example in `~/cheerpj_2.3` or `/Applications/cheerpj_2.3/`. - -**Important:** Converting an applet is documented at the bottom of this page. - -## Converting from .jar to .jar.js - -### Converting a single .jar file - -`cheerpjfy.py` is an helper script that automatically takes care of unpacking, compiling and optimising a whole JAR archive. Using `cheerpjfy.py` is the recommended way of compiling applications and libraries using CheerpJ. - -The basic usage is very simple: - -```shell -/Applications/cheerpj_2.3/cheerpjfy.py my_application_archive.jar -``` - -This command will generate a file called `my_application_archive.jar.js`, which needs to be deployed in the same folder of the original .JAR archive, and hosted on a web server. Instructions on how to serve the converted JavaScript on a web page are provided below. - -**Important:** The files _must_ be accessed through a Web server. Trying to open the HTML page directly from the disk is not supported. The URL must look like `http://127.0.0.1:8080/cheerpj_test.html`, if it looks like `file://c/users/Test/cheerpj_test.html` CheerpJ won't be able to start. - -**Note to Windows users:** You will need to have python3 installed on the system. Python provides a launcher called `py` that will automatically detect and use the right version of python for a given script. To use `cheerpjfy.py` on Windows you need to prefix all the commands with `py`, for example: - -```shell -py c:\cheerpj_2.3\cheerpjfy.py application.jar -``` - -### Converting multiple .jar files - -If your JAR has any dependencies in the form of further JAR archives, the `cheerpjfy.py` command line must be modified as follows: - -```shell -/Applications/cheerpj_2.3/cheerpjfy.py --deps my_dependency_archive.jar my_application_archive.jar -``` - -This command will generate `my_application_archive.jar.js` but **not** `my_dependency_archive.jar.js`. Each archive should be compiled separately by invoking `~/cheerpj_2.3/cheerpjfy.py my_dependency_archive.jar`. - -It is in general safe to put the target JAR in the `--deps` list, although it is not required. If you have an application composed of many JARs you can do something like this: - -``` -for f in one.jar two.jar three.jar -do - ~/cheerpj_2.3/cheerpjfy.py --deps one.jar:two.jar:three.jar $f -done -``` - -## Basic HTML page for testing a Java application - -```html title="index.html" - - - - - CheerpJ test - - - - - -``` - -This page will initialize the CheerpJ system, create a graphical environment to contain all Java windows and then execute the `main` method of `ChangeThisToYourClassName`. The second parameter of cheerpjRunMain is a `:` separated list of JARs where application classes can be found (the classpath). The `/app/` is a virtual file system mount point that reference the root of the web server this page is loaded from. - -You can now serve this web page on a simple HTTP server, such as the http-server utility. - -```shell -http-server [path] [options] -``` - -## Converting an applet - -Applets can be run by Chrome users using the [CheerpJ Applet Runner](https://chrome.google.com/webstore/detail/cheerpj-applet-runner-bet/bbmolahhldcbngedljfadjlognfaaein) Chrome extension. You can also compile the applet ahead of time using the method described above. - -To support all browsers, you can add the following tags to your page: - -```html - - -``` - -This should be sufficient to get the applet to run on any browser, with the pre-compiled JAR.JS's files deployed in the same directory of the original JAR files. The `cheerpjInit({enablePreciseAppletArchives:true});` call can be done during page initialization. - -To avoid potential conflicts with native Java we recommend replacing the original HTML tag with `cheerpj-` prefixed version. You should use ``, `` or `` depending on the original tag. - -## Basic HTML page for testing a Java applet - -```html title="index.html" - - - - - CheerpJ applet test - - - - - -

not able to load Java applet

- - - -``` diff --git a/src/content/docs/cheerpj2/03-getting-started/01-Java-applet.mdx b/src/content/docs/cheerpj2/03-getting-started/01-Java-applet.mdx new file mode 100644 index 00000000..173b3215 --- /dev/null +++ b/src/content/docs/cheerpj2/03-getting-started/01-Java-applet.mdx @@ -0,0 +1,92 @@ +--- +title: Run a Java Applet +--- + +import LinkButton from "../../../../components/LinkButton.astro"; + +CheerpJ can run Java applets in the browser seamlessly. This page will help you getting started with CheerpJ for Java applets. + +**There are two different ways to run a Java Applet in the browser:** + +- Running your own Java applet using the CheerpJ runtime environment and the `` tag in your own webpage. +- Running a public applet using the [CheerpJ Applet Runner](https://chrome.google.com/webstore/detail/cheerpj-applet-runner-bet/) Chrome extension for applets integrated with the applet tag `` in public websites. + +## Running your own applet + +**You will need:** + +- Your applet file(s) +- An HTML file to wrap your applet +- A basic HTTP server to test locally + +### 1. Create a basic HTML file + +```html title="index.html" {7-10, 13-21} + + + + + + CheerpJ applet test + + + + + +

not able to load Java applet

+ + + +``` + +### 2. Host your page locally + +You can now serve this web page on a simple HTTP server, such as the http-server utility. + +```shell +npm install http-server +http-server [path] [options] +``` + +### What's going on? + +- The `cheerpjInit({enablePreciseAppletArchives:true});` initializes CheerpJ runtime environment indicating we are running an applet and not an standalone app. +- The `` tag specifies the code base in a similar manner as the now deprecated `` tag. + +> To avoid potential conflicts with native Java we recommend replacing the original HTML tag with `cheerpj-` prefixed version. You should use ``, `` or `` depending on the original tag. + +## Running a public applet + +### Step 1: Install the CheerpJ applet runner + +CheerpJ Applet Runner is available for Chrome and Edge. + +
+ + + + +
+ +### Step 2: Go to a website with an applet + +Visit a page with a Java applet, [such as this one](http://www.neilwallis.com/projects/java/water/index.php) and click on the CheerpJ Applet Runner icon in the toolbar and enable CheerpJ. + +![](/cheerpj2/assets/cheerpj_applet_demo.gif) diff --git a/src/content/docs/cheerpj2/03-getting-started/00-Tutorial.md b/src/content/docs/cheerpj2/04-guides/AOT-optimization.md similarity index 54% rename from src/content/docs/cheerpj2/03-getting-started/00-Tutorial.md rename to src/content/docs/cheerpj2/04-guides/AOT-optimization.md index 69f08644..1dbcad7a 100644 --- a/src/content/docs/cheerpj2/03-getting-started/00-Tutorial.md +++ b/src/content/docs/cheerpj2/04-guides/AOT-optimization.md @@ -1,38 +1,61 @@ --- -title: Installation +title: AOT Optimization --- -CheerpJ is very easy to use, this tutorial will guide you step by step into compiling an unmodified JAR file to a JAR.JS file. We will also create a basic HTML file integrated with the CheerpJ loader to run the Java application in the browser. +CheerpJ AOT compiler is very easy to use, this page will guide you step by step into compiling an unmodified `.jar` file to a `.jar.js` file. We will also create a basic HTML file integrated with the CheerpJ loader to run the Java application in the browser. -## Download and install CheerpJ +This optimization is not required for running a Java application or applet in the browser but it enhaces performance. Before doing any compilation it is recommended to firstly run your application without the AOT optimization to ensure everything works. + +## 1. CheerpJ AOT compiler installation Visit [our download page](https://leaningtech.com/download-cheerpj/) and download the CheerpJ archive for your platform. CheerpJ is available for Linux, Mac OS X and Windows. CheerpJ is distributed as an archive for all the platforms, you can unpack the archive anywhere in the system. During the tutorial we will assume that CheerpJ has been unpacked in the Applications directory `/Applications/cheerpj_2.3/`. Please keep in mind to use a different path in the following commands if you have chosen a different position or you are using a different version of CheerpJ. -## Using CheerpJ's AOT compiler +## 2. Compiling from `.jar` to `.jar.js` -### Build or download the JAR file +`cheerpjfy.py` is an helper script that automatically takes care of unpacking, compiling and optimising a whole `.jar` archive, you can find it under your CheerpJ installation directory. Using `cheerpjfy.py` is the recommended way of compiling applications and libraries using CheerpJ. -CheerpJ compiles unmodified JAR files to JavaScript so that they can run in the browser. Java source code is not needed to use CheerpJ. If you are building your own application you should already have its JAR file. For this example we will download a basic Swing example. Download the [TextDemo.jar](https://docs.oracle.com/javase/tutorialJWS/samples/uiswing/TextDemoProject/TextDemo.jar) file into a new directory. Below we will assume that this new directory is `~/cheerpj_tutorial/` +### Compiling a `.jar` file -### Build the JAR.JS file +```shell +/Applications/cheerpj_2.3/cheerpjfy.py my_application_archive.jar +``` -CheerpJ provides a convenient python program to convert whole JARs to JavaScript: `cheerpjfy.py`. It supports several options for advanced users, but it's basic syntax is very simple. The following command will generate `TextDemo.jar.js` +This command will generate a file called `my_application_archive.jar.js`, which needs to be deployed in the same folder of the original `.jar` archive, and hosted on a web server. Instructions on how to serve the converted JavaScript on a web page are provided below. + +> **Important:** The files _must_ be accessed through a Web server. Trying to open the HTML page directly from the disk is not supported. The URL must look like `http://127.0.0.1:8080/cheerpj_test.html`, if it looks like `file://c/users/Test/cheerpj_test.html` CheerpJ won't be able to start. + +**Note to Windows users:** You will need to have python3 installed on the system. Python provides a launcher called `py` that will automatically detect and use the right version of python for a given script. To use `cheerpjfy.py` on Windows you need to prefix all the commands with `py`, for example: ```shell -cd ~/cheerpj_tutorial/ -/Applications/cheerpj_2.3/cheerpjfy.py TextDemo.jar +py c:\cheerpj_2.3\cheerpjfy.py application.jar ``` -**NOTE**: `cheerpjfy.py` it's a python3 program, you need to have python3 installed on your system. -**NOTE**: On windows you should prefix the command with the `py` launcher to use the correct version of python. +### Compiling multiple `.jar` files + +If your `.jar` has any dependencies in the form of further `.jar` archives, the `cheerpjfy.py` command line must be modified as follows: -### Create an HTML page +```shell +/Applications/cheerpj_2.3/cheerpjfy.py --deps my_dependency_archive.jar my_application_archive.jar +``` + +This command will generate `my_application_archive.jar.js` but **not** `my_dependency_archive.jar.js`. Each archive should be compiled separately by invoking `~/cheerpj_2.3/cheerpjfy.py my_dependency_archive.jar`. + +It is in general safe to put the target `.jar` in the `--deps` list, although it is not required. If you have an application composed of many `.jar` you can do something like this: + +``` +for f in one.jar two.jar three.jar +do + ~/cheerpj_2.3/cheerpjfy.py --deps one.jar:two.jar:three.jar $f +done +``` + +## 3. Create an HTML page -Copy the following HTML code into `~/cheerpj_tutorial/cheerpj_tutorial.html` +Once we had compiled our java files, we create an HTML page just as we do in our [getting started](/cheerpj2/getting-started) tutorials. The example below is for a [Java application](/cheerpj2/getting-started/Java-app). Java applets can also be compiled in the same manner explained above. -```html title="cheerpj_tutorial/cheerpj_tutorial.html" +```html title="index.html" @@ -44,11 +67,62 @@ Copy the following HTML code into `~/cheerpj_tutorial/cheerpj_tutorial.html` ``` +> **Important:** Please notice that `.jar.js` file(s) are not passed as an argument of `cheerpjRunJar()`, only the location of the `.jar` files is indicated but both `.jar` and `.jar.js` files should be together under the same directory. + +## 4. Host your page locally + +To test CheerpJ you _must_ use a local Web Server. Opening the ``.html` page directly from the disk (for example, by double-clicking on it) is **_not supported_**. This is a very common mistake for first time users. + +> **_TIP_**: There are many different Web servers that you can use, and all of them should work. + +**For a quick test we recommend:** + +```shell title="python 2" +python2 -m SimpleHTTPServer 8080 +``` + +
+ +```shell title="python 3" +python3 -m http.server 8080 +``` + +
+ +```shell title="npm http-server" +http-server -p 8080 +``` + +## Further reading + +- [Startup time optimization](cheerpj2/guides/Startup-time-optimization) +- [Command line options](/cheerpj2/reference/Command-Line-Options) + +--- + +## Using CheerpJ's AOT compiler + +### Build or download the JAR file + +CheerpJ compiles unmodified JAR files to JavaScript so that they can run in the browser. Java source code is not needed to use CheerpJ. If you are building your own application you should already have its JAR file. For this example we will download a basic Swing example. Download the [TextDemo.jar](https://docs.oracle.com/javase/tutorialJWS/samples/uiswing/TextDemoProject/TextDemo.jar) file into a new directory. Below we will assume that this new directory is `~/cheerpj_tutorial/` + +### Build the JAR.JS file + +CheerpJ provides a convenient python program to convert whole JARs to JavaScript: `cheerpjfy.py`. It supports several options for advanced users, but it's basic syntax is very simple. The following command will generate `TextDemo.jar.js` + +```shell +cd ~/cheerpj_tutorial/ +/Applications/cheerpj_2.3/cheerpjfy.py TextDemo.jar +``` + +**NOTE**: `cheerpjfy.py` it's a python3 program, you need to have python3 installed on your system. +**NOTE**: On windows you should prefix the command with the `py` launcher to use the correct version of python. + Let's break down what is going on: - We first include the CheerpJ [loader](https://cjrtnc.leaningtech.com/2.3/loader.js) from our cloud runtime as ``. This file is the only script that needs to be loaded to use CheerpJ. CheerpJ will _automatically_ load all other files, including the `TextDemo.jar.js` we generated above. diff --git a/src/content/docs/cheerpj2/index.md b/src/content/docs/cheerpj2/index.md index f97fd3ef..3f5c734f 100644 --- a/src/content/docs/cheerpj2/index.md +++ b/src/content/docs/cheerpj2/index.md @@ -5,7 +5,7 @@ subtitle: Convert Java to WebAssembly and JavaScript CheerpJ is a Java bytecode to WebAssembly and JavaScript compiler, compatible with 100% of Java, which allows to compile any Java SE application, library or Java applet into a WebAssembly/JavaScript application. -Please visit the project [website](https://leaningtech.com/cheerpj/). +Please visit the project [website](https://cheerpj.com/). **Download latest version**: [![Latest version](https://img.shields.io/badge/cheerpj-2.3-green.svg)](https://leaningtech.com/download-cheerpj/) [![Latest version changelog](https://img.shields.io/badge/2.3-changelog-green.svg)](/cheerpj2/changelog)