Difference between revisions of "Compiling from Source"

From Kolmafia
Jump to navigation Jump to search
(removing ci specific thing)
 
(19 intermediate revisions by 3 users not shown)
Line 1: Line 1:
−
=== GREAT BIG NEWS ===
+
== News ==
 +
''Once great and big, now secondhand news...''
  
−
==KoLmafia has migrated to the GitHub repository and we are retooling for GIT and gradle builds.==
+
===KoLmafia has migrated to the GitHub, GIT and gradle.===
−
Exactly nothing below here is accurate, and we'll need to do a thorough cleanup of this page and the IDE setup page.
+
The Windows, Linux and macOS instructions have been updated, and might have been lightly tested
  
−
The good news is that the IDE setup is a lot easier.  The bad news is you'll need to take some steps to build anything.  In addition, we are discussing changing to a newer required JDK, so even these instructions will not be permanent.
+
The good news is that the [[Development Environment Setup|IDE setup]] is a lot easier.  The bad news is you'll need to take some steps to build anything.   
  
 +
To contribute to the Mafia project, you'll need to be able to install the Java Development Kit, connect to the git repository, and be comfortable writing Java Code. Instructions for the first two are included below:
  
−
 
+
====Windows====
−
To contribute to the Mafia project, you'll need to be able to install the Java Development Kit, connect to the SVN and be comfortable writing Java Code. Instructions for the first two are included below:
 
−
 
 
−
==Windows==
 
 
# Download Tools
 
# Download Tools
−
## Download and install Java Development Kit 1.8 or newer, available from [https://www.oracle.com/java/technologies/javase-downloads.html Oracle] or [https://adoptopenjdk.net AdoptOpenJDK]
+
## Download and install Java Development Kit 17 or newer, available from [https://adoptium.net/temurin/releases/?version=17 Adoptium]. The minimum recommended version is Java 17, but check the *Recommended Java* version on the [https://kolmafia.us KoLmafia Forums] to be up to date].
−
## Download and install Subversion, from [https://subversion.apache.org/packages.html apache.org]
+
## Download and install GIT following the instructions from [https://www.atlassian.com/git/tutorials/install-git#windows Atlassian's GIT install page.]
−
## Download and install Tortoise SVN (or of course, another SVN program)from [https://tortoisesvn.net/downloads.html tortoisesvn]
+
## Download and install Tortoise GIT (if needed) from https://tortoisegit.org
−
## Download and install ANT, from [https://ant.apache.org/bindownload.cgi apache.org]
 
 
# Configure Windows Environment Variables[[File:Environment vars.jpg|thumb|Win 10 Environment Variable Editor]]
 
# Configure Windows Environment Variables[[File:Environment vars.jpg|thumb|Win 10 Environment Variable Editor]]
 
## Windows 10
 
## Windows 10
Line 21: Line 19:
 
### type 'enviro' in the search
 
### type 'enviro' in the search
 
### click on the 'edit environment variables' suggestion
 
### click on the 'edit environment variables' suggestion
−
### add or edit ANT_HOME, JAVA_HOME, and PATH variables<br>''PATH should include ANT_HOME/bin and JAVA_HOME''</br>If ANT or JAVA installers have already set these variables, they can be updated or left alone.
+
### add or edit JAVA_HOME, and PATH variables<br>''PATH should include JAVA_HOME''</br>If the JAVA installer has already set these variables, they can be updated or left alone.
−
# Get Source and Build
+
# Open a new Command Prompt (or Powershell) window and navigate to the directory to which you wish to create kolmafia (e.g. <code>cd %USERPROFILE%\projects</code>, or some similar directory)
−
## Connect to the SVN server and download the source code for the Mafia Project. Using Tortoise SVN, you have to right-click on your desktop, select "SVN Checkout", and put the URL of the repository as "svn://svn.code.sf.net/p/kolmafia/code/". Leave all other settings as they are, and click OK.
+
# Clone the source code for the KoLmafia Project.<br>
−
## Copy %ANT_HOME%/bin/ant.bat to your Desktop/kolmafia/ folder. If you have set up ANT correctly (and it's hard not to - there aren't many options) then double clicking on this file should compile the program.
+
##''If you have a github account:''<syntaxhighlight lang="bash">
−
# Compiling creates a "build" and "dist" folder. The end program is in dist/Kolmafia.jar.
+
git clone git@github.com:kolmafia/kolmafia.git</syntaxhighlight>
−
===Troubleshooting===
+
##''If not:''<syntaxhighlight lang="bash">git clone https://github.com/kolmafia/kolmafia.git</syntaxhighlight>
−
====Double-Clicking ''ant.bat''====
+
# Compile KoLmafia with the Gradle wrapper ''<syntaxhighlight lang="bash">cd kolmafia && gradlew.bat runShadow</syntaxhighlight>''
−
Due to how bat files work when you double-click them, ''ant.bat'' will auto-close before you can read its output.
 
−
# ant assumes that builds are done from a command shell. You'll need to run from the command shell to execute any ant target other than the default, such as ''ant.bat update exec'' or ''ant.bat daily</br>ant -projecthelp'' will list all main targets
 
−
# An easy workaround is to add a "pause" near the bottom of the file before it has a chance to auto-close on you.<br>When you run it again, you'll be able to read its output and it will exit after you ''Press any key to continue...''
 
−
# Alternatively, you can create a wrapper batch file that calls the existing ''ant.bat'' file and adds a pause after executing it.  This method allows you to set different ant targets and also prevents updates to ant from overwriting your modifications.
 
−
<blockquote>Example of a very simple MyWrapper.bat file<pre>
 
−
# This is a wrapper batch file
 
−
# First it runs ant
 
−
call ant.bat daily
 
−
# Then it pauses
 
−
pause</pre></blockquote>
 
  
−
====''tools.jar'' not found====
+
===== Optional =====
−
If you get an error message about "tools.jar" not being found, this means you're trying to build with the JRE (which doesn't contain this file) rather than the JDK (which contains it).<br>
+
If you intend to commit code to GitHub, you will need to follow GitHub's instructions for [https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token adding a Personal Access Token (PAT)]
−
To fix this, right click on ''my computer'' -> ''properties'' -> ''advanced system settings'' -> ''Environment Variables...'' then make sure your PATH contains a reference to the location of your JDK directory.
+
====Linux====
  
−
==Linux==
+
Do once:
 +
# Install git - you probably already have this. If not, follow [https://www.atlassian.com/git/tutorials/install-git#linux this guide.]
 +
# Get an appropriate JDK. If your package manager does not contain a sufficiently up-to-date version of Java, the safest and easiest way to do this is with [https://adoptium.net/installation.html#x64_linux-jdk Adoptium].
 +
# Clone the repo:
 +
## If you have a github account:<syntaxhighlight lang="bash">
 +
git clone git@github.com:kolmafia/kolmafia.git
 +
</syntaxhighlight>If not:<pre>git clone https://github.com/kolmafia/kolmafia.git</pre>
  
−
# Install Sun Java Development Kit ( debian: apt-get install sun-java6-jdk )
+
Do every session:
−
# Install Subversion ( debian: apt-get install svn )
+
# Set up your environment to use that JDK you just downloaded<pre> export PATH="/where/you/put/that/jdk/bin:${PATH}"</pre> (Optionally, put this in your ''.profile'' or ''.bashrc'' if you want to set and forget.)
−
# Install Ant ( debian: apt-get install ant )
+
# Navigate to your cloned repository: <pre>cd /where/you/cloned/kolmafia</pre>
−
# Connect to the SVN server and download the source code for the Mafia Project. ( svn checkout svn://svn.code.sf.net/p/kolmafia/code/ kolmafia )
+
# Get new updates with <pre>git pull</pre>  If you have local uncommitted changes, you may want to instead use ''git stash && git pull && git stash pop''.
−
# Verify tou are using sun-java with ( debian: update-alternatives --all )
+
# Build the new jar: <pre>./gradlew clean shadowJar</pre>
−
# I had to change $JAVA_HOME to compile ( export JAVA_HOME=/usr/lib/jvm/java-6-sun-1.6.0.12 )
 
−
# Compile kolmafia with Ant ( debian: cd kolmafia && ant debian )
 
−
# Install kolmafia ( debian: cd dist && dpkg -i kolmafia*.deb )
 
  
 +
You have a KoLmafia jar file that can be invoked with <pre>java -jar dist/KoLmafia-*.jar</pre>
  
−
'''Above may be out of date.''' As of the move to github the following commands were successful to build from source on Ubuntu 20.04.1 LTS. You will still have to have a jdk installed.<pre>git clone https://github.com/kolmafia/kolmafia.git
+
Do other installation steps as you wish.
−
cd kolmafia
 
−
./gradlew clean shadowJar</pre>
 
−
===Fedora (or probably other RPM systems)===
 
−
 
 
−
# Install Subversion: <pre>sudo yum install sqlite-devel subversion </pre>
 
−
# Install Java JDK: <pre>sudo yum install java-latest-openjdk-devel</pre>
 
−
# Install Ant: <pre>sudo yum install ant</pre>
 
−
# Checkout: <pre>svn checkout svn://svn.code.sf.net/p/kolmafia/code/ kolmafia</pre>
 
−
# Build: <pre>cd kolmafia && ant</pre>
 
−
 
 
  
−
You have a KoLmafia jar file that can be invoked with <pre>java -jar dist/KoLmafia-*.jar</pre>
+
====macOS====
 +
# Verify required packages
 +
## <code>''java --version''</code>
 +
##* if not found or less than Java 17...  Install Java Development Kit version 17 from [https://adoptium.net Adoptium Temurin]
 +
## <code>''git --version''</code>
 +
##* If not found ...  Install git:  Atlassian has a great document on [https://www.atlassian.com/git/tutorials/install-git the various ways to install Git]
 +
# Configure development environment<br>Most of these steps can be included in ''<code>.profile</code>'' or the equivalent for your shell of choice.
 +
## In the terminal set JAVA_HOME to the java home directory. <br>''<code>/usr/libexec/java_home -V</code>'' will list all known values for java_home.<br>If you have multiple copies of java, choose the version you want to use''.'' <code>''export JAVA_HOME=`/usr/libexec/java_home -v17''</code>
 +
# Open a new terminal window and navigate to the directory to which you wish to create kolmafia (e.g. <code>cd ~/projects</code>, or some similar directory)
 +
# Clone the source code for the KoLmafia Project.<br>
 +
##''If you have a github account:''<syntaxhighlight lang="bash">
 +
git clone git@github.com:kolmafia/kolmafia.git</syntaxhighlight>
 +
##''If not:''<syntaxhighlight lang="bash">git clone https://github.com/kolmafia/kolmafia.git</syntaxhighlight>
  
−
Do other installation steps as you wish.
+
Do every session:
  
−
==MacOSX==
+
# Navigate to your cloned repository: <pre>cd ~/projects/kolmafia</pre>
−
# Install required packages</br>''MacOS X packages for Java, subversion, and ANT may also be installed via a package manager like [https://brew.sh Homebrew] or [https://www.macports.org MacPorts].  The instructions are written for a direct installation of the packages.''
+
# Get new updates with <pre>git pull</pre> If you have local uncommitted changes, you may want to instead use ''git stash && git pull && git stash pop''.
−
## Install Java Development Kit version 1.8 or newer from [https://www.oracle.com/java/technologies/javase-downloads.html Oracle] or [https://adoptium.net Adoptium Temurin]
+
# Compile KoLmafia with the Gradle wrapper: ''<syntaxhighlight lang="bash">./gradlew runShadow</syntaxhighlight>''
−
## Install git:  Atlassian has a great document on [https://www.atlassian.com/git/tutorials/install-git the various ways to install Git]
 
−
# Configure development environment</br>Most of these steps can be included in ''.profile'' or the equivalent for your terminal of choice.
 
−
## In the terminal set JAVA_HOME to the java home directory. </br>''/usr/libexec/java_home -V'' will list all known values for java_home.</br>If you have multiple copies of java, choose the version you want to us''e.
 
−
# Open a new terminal window and navigate to the directory to which you wish to create kolmafia (e.g. cd ~/Projects, or some similar directory)
 
−
# Clone the source code for the KoLmafia Project.</br>''git clone git@github.com:kolmafia/kolmafia.git''
 
−
# Compile KoLmafia with the Gradle wrapper (''cd kolmafia && ./gradlew runShadow'')
 
−
''There are more instructions on setting up your token in GitHub and then setting up ssh-agent, as well as how to update your cloned copy.  TBD''
 
  
 +
=== Optional ===
 +
If you intend to commit code to GitHub, you will need to follow GitHub's instructions for [https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token adding a Personal Access Token (PAT)]
 
''[[Category:Tech Support]]''
 
''[[Category:Tech Support]]''

Latest revision as of 01:00, 5 December 2023

News

Once great and big, now secondhand news...

KoLmafia has migrated to the GitHub, GIT and gradle.

The Windows, Linux and macOS instructions have been updated, and might have been lightly tested

The good news is that the IDE setup is a lot easier. The bad news is you'll need to take some steps to build anything.

To contribute to the Mafia project, you'll need to be able to install the Java Development Kit, connect to the git repository, and be comfortable writing Java Code. Instructions for the first two are included below:

Windows

  1. Download Tools
    1. Download and install Java Development Kit 17 or newer, available from Adoptium. The minimum recommended version is Java 17, but check the *Recommended Java* version on the KoLmafia Forums to be up to date].
    2. Download and install GIT following the instructions from Atlassian's GIT install page.
    3. Download and install Tortoise GIT (if needed) from https://tortoisegit.org
  2. Configure Windows Environment Variables
    Win 10 Environment Variable Editor
    1. Windows 10
      1. Go to settings
      2. type 'enviro' in the search
      3. click on the 'edit environment variables' suggestion
      4. add or edit JAVA_HOME, and PATH variables
        PATH should include JAVA_HOME
        If the JAVA installer has already set these variables, they can be updated or left alone.
  3. Open a new Command Prompt (or Powershell) window and navigate to the directory to which you wish to create kolmafia (e.g. cd %USERPROFILE%\projects, or some similar directory)
  4. Clone the source code for the KoLmafia Project.
    1. If you have a github account:
      git clone git@github.com:kolmafia/kolmafia.git
    2. If not:
      git clone https://github.com/kolmafia/kolmafia.git
  5. Compile KoLmafia with the Gradle wrapper 
    cd kolmafia && gradlew.bat runShadow
Optional

If you intend to commit code to GitHub, you will need to follow GitHub's instructions for adding a Personal Access Token (PAT)

Linux

Do once:

  1. Install git - you probably already have this. If not, follow this guide.
  2. Get an appropriate JDK. If your package manager does not contain a sufficiently up-to-date version of Java, the safest and easiest way to do this is with Adoptium.
  3. Clone the repo:
    1. If you have a github account:
      git clone git@github.com:kolmafia/kolmafia.git
      If not:
      git clone https://github.com/kolmafia/kolmafia.git

Do every session:

  1. Set up your environment to use that JDK you just downloaded
     export PATH="/where/you/put/that/jdk/bin:${PATH}"
    (Optionally, put this in your .profile or .bashrc if you want to set and forget.)
  2. Navigate to your cloned repository: 
    cd /where/you/cloned/kolmafia
  3. Get new updates with 
    git pull
    If you have local uncommitted changes, you may want to instead use git stash && git pull && git stash pop.
  4. Build the new jar: 
    ./gradlew clean shadowJar

You have a KoLmafia jar file that can be invoked with 

java -jar dist/KoLmafia-*.jar

Do other installation steps as you wish.

macOS

  1. Verify required packages
    1. java --version
      • if not found or less than Java 17... Install Java Development Kit version 17 from Adoptium Temurin
    2. git --version
  2. Configure development environment
    Most of these steps can be included in .profile or the equivalent for your shell of choice.
    1. In the terminal set JAVA_HOME to the java home directory.
      /usr/libexec/java_home -V will list all known values for java_home.
      If you have multiple copies of java, choose the version you want to use. export JAVA_HOME=`/usr/libexec/java_home -v17
  3. Open a new terminal window and navigate to the directory to which you wish to create kolmafia (e.g. cd ~/projects, or some similar directory)
  4. Clone the source code for the KoLmafia Project.
    1. If you have a github account:
      git clone git@github.com:kolmafia/kolmafia.git
    2. If not:
      git clone https://github.com/kolmafia/kolmafia.git

Do every session:

  1. Navigate to your cloned repository: 
    cd ~/projects/kolmafia
  2. Get new updates with 
    git pull
    If you have local uncommitted changes, you may want to instead use git stash && git pull && git stash pop.
  3. Compile KoLmafia with the Gradle wrapper: 
    ./gradlew runShadow

Optional

If you intend to commit code to GitHub, you will need to follow GitHub's instructions for adding a Personal Access Token (PAT) '

Retrieved from "https://wiki.kolmafia.us/index.php?title=Compiling_from_Source&oldid=9234"