Skip to content

Building bb4 Projects

Jump to bottom
Barry G Becker edited this page Nov 26, 2021 · 83 revisions

These are detailed instructions on how to build and release bb4 projects. If you want to create a new bb4 project, see the bb4-project-template.

Prerequisites

If you have not already done so, install the following

  • Java SE Development Kit (JDK). Make sure you get the version 11+ JDK (not the JRE). After installing, set the JAVA_HOME environment variable to point to the install location. Setting JAVA_HOME is not strictly necessary, but it will save you from having to tell Intellij where it is later.
  • Git - When installing, you should be able to just accept all the defaults. Though not required, you should consider creating your own GitHub account. I think it is simpler to install Git instead of the Windows GitHub app, though both should work. The GitHub app has git.exe, but it puts it in a strange place.
  • Intellij IDEA - The free community edition is fine. Eclipse will work also, but Intellij is a better IDE. The bb4 projects use Gradle to build, but you do not need to install it because the Gradle wrapper is used. It will automatically download the required version.

Building

Once you have the prerequisites, these are the steps to build.

  1. Clone the git repository using git clone https://github.com/barrybecker4/bb4-common.git You can substitute for bb4-common if you are trying to build one of the downstream projects. You can also clone using the Windows GitHub app, if you have it, or clicking the "clone to desktop" button in GitHub.
  2. Run gradlew at the root. This will compile and test all the code. If in Linux or Cygwin or gitBash use ./gradlew
  3. Run gradlew tasks to see what tasks are available. If it is not a library project, there should be tasks that will run applications directly. Also try running gradlew tasks to show a list of all available gradle tasks.
  4. If you want to view and edit files in Intellij, run gradle idea. Next, open Intellij IDEA and open the top level folder containing the bb4 project. It is also possible to open the project by just opening the build.gradle file in Intellij. If you see a message about an unregistered git root, this is easy to fix, by just clicking "configure" and adding the root. All Gradle tasks can be run from within Intellij (using Gradle window on the right). It's possible that you will have to configure Gradle in Intellij initially. To do so, point the Gradle project to the build.gradle file, and check the option to use the gradle wrapper. Also set the service directory to <path-to-bb4-project>/.gradle.

Releasing New Versions

  • Each module is versioned. During development, SNAPSHOT versions are used.
  • When ready to release, remove the -SNAPSHOT suffix from the version (in gradle file) and push the artifacts to the Sonatype maven repository for general consumption (if you have the authorization to do so - see below). Start with the most upstream module in dependency order (bb4-gradle).
    ./gradlew build publishArtifacts --info
    Unlike a SNAPSHOT release, a final release cannot be changed once released.
  • Once the staged jars have been published they need to be promoted on Sonatype. Click the "staging repositories" item on the left, look for your newly published stg artifact (e.g. bb4-gradle), or see them all by searching for com.barrybecker4. Close it in order to do validation, then release it to the wild if everything is OK. It takes a few minutes after closing before you can release, and it takes even more minutes after releasing until it appears at https://repo1.maven.org/maven2/com/barrybecker4/ and you can use it as a dependency in a build.
  • Prior to release, while SNAPSHOTs are being used, the flow will go something like this: When you need to update one of the framework modules (e.g. common, ui, etc) use
    ./gradlew build publishArtifacts --info
    to build and publish the SNAPSHOT version. Then to build the downstream dependent module(s) use
    ./gradlew clean build idea --refresh-dependencies
    The idea task will rebuild Intellij project files, and --refresh-dependencies ensures that you get the artifact just deployed and not a cached version. If it happens to be a Scala project using sbt, then the command is sbt update compile test. If you are working within Intellij, you can get the new SNAPSHOT dependency by clicking on "refresh" in the Gradle panel on the right side of the IDE.
  • After the release has been completed for all projects, bump the version number and add -SNAPSHOT to it again so that development can continue for the next release.

Deploying to a Website

From 2000 to 2016, I deployed my projects to my website using applets and java-webstart. However, in recent years, browsers have dropped support for applets, and recent versions of Java have even dropped support for java-webstart. As a result, I now just deploy html and a zip file for each project independently using the Gradle "deploy" task. This new method is simpler to implement, but adds a little more complexity for the user. They need to first download a zip file, unzip it, and then run a specified command. Not too hard, but harder than just clicking the link and having it run.

All the bb4 projects, that are not library projects, now can use the Gradle deploy task to deploy to a dist/bb4-<project> directory. Then Filezilla (or similar tool) can be used to ftp the files to any website docroot.

Since I use InfinityFree for hosting (to save money), files larger than 10m are not allowed. To work around this, I create a Github release containing the zip file and link to that from the index.html file.

Additional notes

  • If you are an admin and have permissions to release new versions (rare), then you will need to specify your credentials in a ~/.gradle/gradle.properties file. This file should not be checked into version control. The contents are in KeyPass in Sonatype entry, and the secring.gpg is in box.net.
  • If deploying to barrybecker4.com, follow the readme in the bb4-website project.
  • Intellij troubleshooting tips
    • If you change gradle configuration, you may need to run gradlew cleanIdea idea to make sure Intellij configuration is up to date. I think this may not be needed in new versions of Intellij.
    • Update Project Structure | Project SDK so that the JDK points to the install location of your JDK. This usually happens automatically.
    • In Intellij | project structure, select SDK and compiler output path to be something like "output".
    • If there are red errors in the code, go into project structure | libraries. Select them all and do right-click "add to modules".
    • In Intellij | settings |compiler, verify ?*.au is in the patterns list, and -ea (enable assertions) is in the JVM param list.
    • All runnable classes can be run or debugged from within Intellij by right-clicking on them.
  • Linux tips:
    • Install OpenJdk java. As root, save or move the downloaded jdk1.11.tar.gz to the installation location (e.g. /usr/local/java). Install with tar -xzvf jdk1.11.tar.gz.
    • Install Intellij community edition. As root, save or move the downloaded idealC-.tar.gz to the installation location (e.g. /usr/local/IDEA). Install with tar -xzvf idealC-.tar.gz.
    • Set JAVA_HOME and add to path. Most applications that use java will look for it in JAVA_HOME. Adding executables to your path means you can run them without specifying the full path. Try adding the following to your ~/.bashrc file and then run source .bashrc. Make sure the locations and jdk version match what you have installed.
      export JAVA_HOME=/usr/local/java/jdk1.8.0_45
      export PATH=$HOME/.local/bin:$HOME/bin:$JAVA_HOME/bin:/usr/local/IDEA/idea-IC-129.1359/bin:$PATH
    • If it says you do not have permission to execute a file, as root, enter chmod +x <filename> to add executable permission.
    • If using cygwin you may need to run dos2unix on the gradlew file before it will work.
  • Jenkins tips. It is possible to setup jenkins as a build server. This can automatically build and deploy modules whenever git checkins are made. I did this, but had a few minor issues.
    • On windows, it uses C:\Windows\System32\config\systemprofile for user.home instead of ~. I could not find a way to change it. This means that the .gradle/gradle.properties with the private key needs to go here in order to publish through jenkins.
  • All the bb4 projects can be organized into a dependency hierarchy that looks something like this:
  (bb4-gradle)

   bb4-math      __bb4-common____
           \   /                 \
           bb4-ui             bb4-sound     bb4-A-star
             /  \                /\              \
            /    \______________/__\______________\____________________
        bb4-optimization       /    /    \         \    \              \
          /          \        /    /      \         \  bb4-adventure   bb4-aikido-appication
    bb4-imageproc     \      /    /        \         \    
      |         bb4-experiments  /          \         \    bb4-expression
      |                         /            \         \     /
      |                   bb4-puzzles    bb4-games     bb4-simulations               
     bb4-image-breeder

All modules are open-source projects in github (https://github.com/bb4) Pure library projects are: bb4-common, bb4-math, bb4-expression, bb4-ui, bb4-sound, bb4-A-star, bb4-optimization, bb4-imageproc

  • Contact barrybecker4<at>gmail.com if you have questions or comments.
Clone this wiki locally