Command-line Builds

CS 240: Advanced Software Construction

The Need for Command-line Builds

“Building” Software

• Building software requires a lot of steps:
• Retrieving source code
• Downloading/resolving dependencies
• Compiling code
• Compiling and running automated tests
• Measuring test coverage
• Packaging compiled code into a distributable format
• Installing/deploying the software
• IDEs are great, but manually building software with only an IDE can be laborious and error-prone

​

Command-line Builds

• Command-line builds are often preferred
• Anyone can compile, test, verify, and deploy the software with simple shell commands
• The processes for building the software are clearly defined and repeatable
• Command-line builds support continuous integration and deployment
• For example, when code is committed to a Github repository, Github Actions can be used to automatically compile, test, verify, and deploy the software

Command-line Builds

• Most language environments have tools for doing command-line builds
• Java: Maven, Gradle
• C/C++: Make
• Javascript: npm
• Python: Poetry, PyBuilder
• Universal: Shell scripts
• We will use Maven to demonstrate typical build tool features
• Demonstration: Maven build for the Chess project
• mvn clean
• deletes artifacts created from prior builds (so you can start from scratch)
• mvn install
• compiles, packages, tests, and installs the project in the local Maven repository
• mvn site
• generates a website for the project containing quality reports and documentation

Command-line Builds

• Demonstration: Running the Server and Client
• With Maven
• cd server; mvn exec:java
• cd client; mvn exec:java

​

• Without Maven
• The output of the server build is an “executable JAR” file you can run on the command-line named server-1.0-jar-with-dependencies.jar
• cd server/target; java –jar server-1.0-jar-with-dependencies.jar
• The output of the client build is an “executable JAR” file you can run on the command-line named client-1.0-jar-with-dependencies.jar
• cd client/target; java –jar client-1.0-jar-with-dependencies.jar

​

​

​

Maven Project Structure

Project Structure

• Maven defines a standard directory and file structure for projects
• By conforming to the standard structure, you get a lot of build functionality for free
• The pom.xml file in the project root directory is the configuration file for the project

​

​

Generate new project

• Maven can automatically generate a new project directory and file structure
• mvn archetype:generate -DgroupId=edu.byu.cs240 -DartifactId=chess -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false
• Demo: Creating chess project
• Use mvn archetype:generate to create “chess” project
• Review the generated directory and file structure

Multi-module Projects

• Larger projects will be organized into multiple modules
• Example: Chess has “server”, “client”, and “shared” modules
• Demonstration: Creating a multi-module project
• In the chess/ directory, use mvn archetype:generate to generate sub-module projects named server, client, and shared
• Modify chess/pom.xml to be a “parent” pom.xml
• Modify sub-module pom.xml files to reference chess/pom.xml

Dependencies

Dependencies

• Chess dependencies
• GSON, MySQL driver, Javalin, Web socket libraries
• Maven maintains an online repository of available code libraries
• mvnrepository.org
• Maven automatically downloads dependencies as part of the build process
• Dependency structure

<dependency>

<groupId>com.google.code.gson</groupId>

<artifactId>gson</artifactId>

<version>2.10.1</version>

<scope>compile</scope> -- or “test” or “runtime”

</dependency>

Dependencies

• Maven downloads and caches dependencies in a local repository, by default in the .m2 folder in the user's home directory
• When a project is built, the output JAR files are also installed in the local repository
• Example: Dependencies in Chess pom.xml files
• Dependency versions are often specified in the parent pom.xml so all modules use the same versions
• Sub-module pom.xml files reference only the dependencies they actually need

​

Local JAR File Dependencies

• If you have a JAR dependency that is not available in mvnrepository.org, you can install the JAR file into your local Maven repository
• Example: Chess passoff-dependencies.jar file
• mvn install:install-file -Dfile=libs\passoff-dependencies.jar -DgroupId=edu.byu.cs240 -DartifactId=passoff-dependencies -Dversion=1.0 -Dpackaging=jar

Plugins

Plugins

• Maven has a “plugin” architecture
• Maven’s core features are implemented as plugins
• Available plugins can be found at
• https://maven.apache.org/plugins/
• Third-parties can also write plugins
• https://www.mojohaus.org
• https://www.eclemma.org/jacoco/

Plugins

• There are two types of plugins

​

• “Build plugins” that run during the build process (compile, test, package, install)
• mvn install

​

• “Reporting plugins” that run during documentation website generation
• mvn site

​

Plugins

• Build plugins for Chess

• Reporting plugins for Chess

Plugins

• Example: Plugins in Chess pom.xml files
• Plugin versions are often specified in the parent pom.xml so all modules use the same versions

​

• Sub-module pom.xml files reference only the plugins they actually need

​

How Plugins Work

Plugin “Goals”

• Each plugin implements a group of “goals” (i.e., “commands”) it can run
• Examples from https://maven.apache.org/plugins/
• To list a plugin’s goals, run mvn <plugin>:help
• Plugin goals can be manually executed from the command-line
• mvn <plugin>:<goal>
• Examples
• mvn compiler:testCompile - Compile the test code
• mvn surefire:test - Run test cases
• mvn checkstyle:checkstyle - Generate test code coverage report
• mvn compiler:testCompile surefire:test checkstyle:checkstyle - Execute all three goals in order

​

Plugin “Goals” and the Build Lifecycle

• Plugin goals can be run manually, but usually they are executed automatically by Maven at appropriate points during the build process
• A Maven build goes through a sequence of “phases” called the “build lifecycle”
• Lifecycle Overview
• mvn deploy lifecycle (or “default lifecycle”)
• mvn site lifecycle
• mvn clean lifecycle

Plugin “Goals” and the Build Lifecycle

• By default, each plugin goal is bound to zero or more phases
• When a project includes a plugin, the plugin’s goals will run during the lifecycle phases to which they are bound
• Examples
• compiler:compile runs during the compile phase
• compiler:testCompile runs during the test-compile phase
• surefire:test runs during the test phase
• jacoco:report runs during the verify phase
• To list all plugin goals that will run during a particular phase, run mvn help:describe -Dcmd=<phase>
• mvn help:describe –Dcmd=compile

​

IDE + �Automated Builds

IDE + Automated Build Tool

• Automated builds are great, but do you really want to give up your IDE to get them?
• When an IDE builds a project, it needs to do many of the same things an automated build does (compile code, compile tests, run tests, generate coverage reports, etc.)
• IDEs often have their own internal build systems, but some can also use external build tools instead (like Maven)
• This gives you the best of both worlds: IDE tools + automated builds

IDE + Command-line Build Tool

• Example: IntelliJ
• By default, IntelliJ uses its own internal build system
• But, IntelliJ can also create and manage Maven and Gradle projects
• IntelliJ “New Project” dialog lets you select which build system the project should use
• Demonstration
• Create a Maven IntelliJ project
• Copy Chess code into the project
• We get both IDE features and command-line builds