[GitHub] [cassandra-website] michaelsembwever commented on a change in pull request #79: build and test documentation improvements

[GitBox <gi...@apache.org>]

michaelsembwever commented on a change in pull request #79:
URL: https://github.com/apache/cassandra-website/pull/79#discussion_r745332172



##########
File path: site-content/source/modules/ROOT/pages/development/ide.adoc
##########
@@ -2,68 +2,84 @@
 
 == Building and IDE Integration
 
-=== Building From Source
+=== Prerequisites
 
-Building Cassandra from source is the first important step in contributing
-to the Apache Cassandra project.
-You'll need to install http://www.oracle.com/technetwork/java/javase/downloads/index.html[Java 8], https://git-scm.com/[Git], and http://ant.apache.org/[Ant] first.
+Building Cassandra from source is the first important step in contributing to the Apache Cassandra project.
+You will need to install Java (JDK 8 or 11, depending on which version
+you want to build Cassandra against, best is to install both and then
+switch between them when needed), Git, and Ant (including ant-optional).
+
+=== Getting the source code
 
 The source code for Cassandra is shared on the central Apache Git
 repository and organized by branch, one branch for each major version.
-You can access the code for the current development branch using:
+You can access the code for the current development branch at
+https://gitbox.apache.org/repos/asf/cassandra.git (the primary location)
+or at https://github.com/apache/cassandra (a mirror location).
 
-// 01.15.21 - polandll - should this step be a fork rather than a clone?
+However, to develop a patch or a new feature, you should fork the Cassandra
+project first and then clone it from your own fork:
 
-[source, plaintext]
+[source,plaintext]
 ----
-git clone https://gitbox.apache.org/repos/asf/cassandra.git cassandra-trunk
+git clone https://github.com/<your_git_name>/cassandra.git cassandra
 ----
 
-Other branches will point to different versions of Cassandra. Switching
-to a different branch requires checking out the branch.
-For example, to checkout the latest version of Cassandra 3.0, use:
+=== Building Cassandra
 
-[source, plaintext]
-----
-git checkout cassandra-3.0
-----
+Cassandra is a Java project which is built using Ant.
+The build file, `build.xml` located in the root of the project content,
+has various tasks defined (you can list all of them with some short
+descriptions by running `ant -p`).
 
-You can get a list of available branches with `git branch`.
+The build uses the Java compiler which is currently set up in your
+shell. By default, the build uses Java 8. If you want to build
+with Java 11, you need to either add a build property `-Duse.jdk11=true`
+to your Ant build command or export the environment variable
+`CASSANDRA_USE_JDK11=true`. Otherwise, if you run the build using
+Java 11, the build script complains.
 
-Build Cassandra using ant:
+Now you can build Cassandra with the default task - just execute
+`ant` or `ant jar`. This may take a significant amount of time depending
+on artifacts that have to be downloaded or the number of classes that
+need to be compiled. When the build completes, you can find a JAR file
+in the build directory, and the database service can be started with
+the `bin/cassandra` script.
 
-[source, plaintext]
-----
-ant
-----
+=== Building a distribution
 
-This may take a significant amount of time depending on artifacts that have to
-be downloaded or the number of classes that need to be compiled.
+Some tasks you might be interested in are:
+
+* `sources-jar` - produce accompanying JAR for the primary Cassandra
+artifact (also in the build directory)
+* `artifacts` - generate Cassandra distribution in `build/dist`
+directory and package it to `tar.gz` (with and without sources)
 
 [TIP]
 .Hint
 ====
-You can setup multiple working trees for different Cassandra versions
-from the same repository using
-https://git-scm.com/docs/git-worktree[git-worktree].
+Remember to have only one Cassandra JAR artifact in the build directory;

Review comment:
       `ant artifacts` generates the following `apache-cassandra*.jar` files…
   ```
   ❯ ls build/apache-cassandra*.jar
   build/apache-cassandra-4.0.2-SNAPSHOT-javadoc.jar build/apache-cassandra-4.0.2-SNAPSHOT-sources.jar build/apache-cassandra-4.0.2-SNAPSHOT.jar
   ```




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: pr-unsubscribe@cassandra.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: pr-unsubscribe@cassandra.apache.org
For additional commands, e-mail: pr-help@cassandra.apache.org