Build instructions

[jeremydouglass]

@gaocegege -- what are the current build instructions?

CONTRIBUTING.md says "Read the README.md for build instructions" -- but it doesn't have build instructions. I'm looking through various artifacts -- docker, travis, appveyor, a build.xml for ant (eclipse?), and a set of scripts, e.g. deploy -- and trying to reconstruct a build setup for when I roll up a new release.

[gaocegege]

I will file a PR to add build instructions into README.

[gaocegege]

@jeremydouglass

I think we have docs about building here: https://github.com/processing-r/Processing.R/blob/master/raw-docs/devel/compilation.md

Do you need the docs about how to release a mode into docs/?

[jeremydouglass]

Great, thank you -- I will read https://github.com/processing-r/Processing.R/blob/master/raw-docs/devel/compilation.md and see if i can create a build.

A new build for 1.0.7 should only change urls in the documentation and the build number, but hopefully it will get Contributions Manager installs working again in #254, as it can now list and download the zip, but fails to install.

[jeremydouglass]

Do you need the docs about how to release a mode into docs/?

Yes, that would be very helpful!-- mode release instructions.

When I was last building I was building straight into my local PDE for testing, but now this is for distribution.

[jeremydouglass]

@gaocegege -- I have continuous integration on travis and appveyor working.

To build a new release locally, this is what I figured out:

cd scripts
./deploy.sh 107 v1.0.7
# upload docs/RLangMode.zip to https://github.com/processing-r/Processing.R/releases/

However I am not sure about rebuilding the documentation files and updating https://processing-r.github.io/.

Could you help with doc build instructions please?

[gaocegege]

Yeah, of course. I am trying to build the docs from scratch. I was using macOS when I built the docs website. Now I am using Linux. I cannot build Processing now since I did not install the JDK 6.

We need to build Processing and Processing.R runner.jar first, then we can use the runner.jar to build the docs website.

[jeremydouglass]

Thanks so much for looking at it.

We need to build Processing and Processing.R runner.jar first, then we can use the runner.jar to build the docs website.

Got it. I've now also run into a build problem on Mac for the mode. I have jdk 10, and it needs jdk 8 (not 6) -- which I have installed, but somehow setting export JAVA_HOME=$(/usr/libexec/java_home -v 1.8) before running deploy.sh isn't actually working. When I install the rebuilt version through Contributions Manager I'm getting:

err is java.lang.UnsupportedClassVersionError: rprocessing/mode/RLangMode has been compiled by a more recent version of the Java Runtime (class file version 54.0), this version of the Java Runtime only recognizes class file versions up to 52.0

I've also noticed that the mode.properties created by deploy doesn't seem formatted in the expected way to match the previous distribution -- that one might have been hand-edited. Tried manually editing it, but I'll look over the template / generator script later.

[jeremydouglass]

On MacOS I was able to upload a valid version of releases/v1.0.7 that installs in Contributions Manager without errors (build not including updated docs).

1. install Java jdk 8u192:

/Library/Java/JavaVirtualMachines/jdk1.8.0_192.jdk/

2. define JAVA_HOME

Add a line to the Processing.R scripts/deploy.sh defining JAVA_HOME. I used the mac java_home command, but this can just be a path.

function deploy {
  export JAVA_HOME=$(/usr/libexec/java_home -v 1.8)
  echo $JAVA_HOME

This gives the Contents/Home of the Java 8 jdk
/Library/Java/JavaVirtualMachines/jdk1.8.0_192.jdk/Contents/Home

I tried exporting JAVA_HOME from the shell and then running deploy.sh, but it did not work.

3. in deploy.sh, fix the path to generator-util.sh:

I'm running deploy.sh from its own directory -- BASH_SOURCE isn't defined / isn't loading through source like it should, so source is giving a file-not-found error for generator-util.sh. Change line to:

-  source "$(dirname "${BASH_SOURCE}")/utils/generator-util.sh"
+  source "${PWD}/scripts/utils/generator-util.sh"

4. Run deploy.sh

cd scripts
./deploy.sh 107 v1.0.7

The log may show a warning that will also indicate it is correctly using 1.8 (jdk8):

[javac] warning: Supported source version 'RELEASE_6' from annotation processor 'org.eclipse.sisu.scanners.index.SisuIndexAPT6' less than -source '1.8'

5. test install of the new mode by unzipping RLangMode.zip to Processing/modes and restarting Processing. The mode "R" should appear in the dropdown menu, launch a new R sketch window, and run an R sketch from examples.

6. commit docs/RLangMode.txt and tag that commit or later for release (e.g. v1.0.7).

7. create a release on github. Upload as release attachments:

   1. docs/RLangMode.txt from docs (not the one from dist), and
   2. docs/RL:angMode.zip

Also, re: "I've also noticed that the mode.properties created by deploy doesn't seem formatted in the expected way to match the previous distribution" -- I was wrong. dist/mode.properties does look different, but the version that ends up in the zip is correct.

[jeremydouglass]

Need to clean up the docs configuration as well.

Currently, docs are on GitHub pages here:

https://processing-r.github.io/

...and they link to https://github.com/gaocegege/Processing.R, which is outdated and autoforward to https://github.com/processing-r/Processing.R.

That repo (this one, the main one) has GitHub pages activated -- it builds out of master:/docs to

https://processing-r.github.io/Processing.R/

...but master:/docs doesn't contain the docs, just the release, and so the link 404.

Edit: I disabled this now.

Instead, the website is published out of the default org GitHub Pages repo:

https://github.com/processing-r/processing-r.github.io

...and it should be updated and committed by running the doc-tools repo:

https://github.com/processing-r/Processing.R-docs-tools

...on the contents of the main mode repo. We just need to reconstruct how to do that -- the scripts in doc-tools are unclear.

[jeremydouglass]

As far as I can tell, on the doc-tools site, the entry point is:

scripts/generate-reference.sh

and the undocumented command line arguments that should be passed through to src/generate.py are

--core      The location of Processing.R source code.
--jar       The location of runner.jar
--docs-dir  The location of Processing.R docs

So we need to provide the runner.jar location. However, the dist doesn't build a runner.jar. I found a reference in the Dockerfile:

# Build Runner.jar
RUN bash .docker/generate-ant-file-in-docker.sh && \
    ant try && \
    mv try/RLangMode.jar /code/runner

and then in generate-ant-file-in-docker.sh:

# Those paths are important to build runner.jar.
core="/code/processing/core/library"
pde="/code/processing/lib/pde.jar"
version="docker"

...but I don't see anything there that would specifically create a runner.jar.

I'm just guessing here, but is it possible that runner.jar could only be created through docker, and the when docker was deprecated the docker-specific build info for runner was removed from build.xml? The way that I see to recover the build environment is to go to an old docker container:

https://quay.io/repository/gaocegege/processing.r?tab=history

[jeremydouglass]

@gaocegege -- wait. is "runner.jar" actually RLangMode.jar?

That is what it looks like in the dockerfile.

If that is the case, that would make things easier....

Processing.R/Dockerfile

Lines 51 to 55 in e13afbe

	# Build Runner.jar
	RUN bash .docker/generate-ant-file-in-docker.sh && \
	ant try && \
	mv try/RLangMode.jar /code/runner

[gaocegege]

@jeremydouglass

We can run ant try to build the runner.jar locally.

[gaocegege]

Code is here https://github.com/processing-r/Processing.R/blob/master/build.xml.template#L119