Difference between pages "Help:To Do List" and "Compiling from Source"

Revision as of 00:56, 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

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
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.
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)

Clone the source code for the KoLmafia Project.

If you have a github account:

git clone git@github.com:kolmafia/kolmafia.git

If not:

git clone https://github.com/kolmafia/kolmafia.git

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:

Install git - you probably already have this. If not, follow 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 Adoptium.

Clone the repo:

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:

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.)
Navigate to your cloned repository:
```
cd /where/you/cloned/kolmafia
```
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.
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

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
  - If not found ... Install git: Atlassian has a great document on the various ways to install Git
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
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.

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:

Navigate to your cloned repository:
```
cd ~/projects/kolmafia
```
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.
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) '

Difference between pages "Help:To Do List" and "Compiling from Source"

Revision as of 00:56, 5 December 2023

Contents

News (once great and big, now secondhand news)

KoLmafia has migrated to the GitHub, GIT and gradle.

Windows

Optional

Linux

macOS

Optional

Navigation menu

Search

@@ Line 1: / Line 1: @@
-{{TOCright}}
+=== News (once great and big, now secondhand news) ===
-== "To Do" List ==
+==KoLmafia has migrated to the GitHub, GIT and gradle.==
+The Windows, Linux and macOS instructions have been updated, and might have been lightly tested
-This is a list of stuff that is missing from the wiki or else needs major work. Please help!
+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:
-If you need tips for editing the wiki, find that here: [[Help:Editing]].
+==Windows==
+# Download Tools
+## 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 GIT following the instructions from [https://www.atlassian.com/git/tutorials/install-git#windows Atlassian's GIT install page.]
+## Download and install Tortoise GIT (if needed) from https://tortoisegit.org
+# Configure Windows Environment Variables[[File:Environment vars.jpg|thumb|Win 10 Environment Variable Editor]]
+## Windows 10
+### Go to settings
+### type 'enviro' in the search
+### click on the 'edit environment variables' suggestion
+### 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.
+# 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)
+# 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>
+# Compile KoLmafia with the Gradle wrapper ''<syntaxhighlight lang="bash">cd kolmafia && gradlew.bat runShadow</syntaxhighlight>''
-*CLI Commands are usually only added to the [[CLI Reference]]. Only very complicated commands require their own page.
+=== 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)]
+==Linux==
-*ASH commands need to be listed on their category page as well as on the [[Ash Functions]] list.
+Do once:
-**It is not necessary to always create a code sample, although it is preferred.
+# Install git - you probably already have this. If not, follow [https://www.atlassian.com/git/tutorials/install-git#linux this guide.]
-**If you don't add a code sample, please remember to add '''needscode=yes|''' to the page.
+# 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>
+Do every session:
+# 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.)
+# Navigate to your cloned repository: <pre>cd /where/you/cloned/kolmafia</pre>
+# 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''.
+# Build the new jar: <pre>./gradlew clean shadowJar</pre>
-== Missing Stuff ==
+You have a KoLmafia jar file that can be invoked with <pre>java -jar dist/KoLmafia-*.jar</pre>
-: ash function format_dtg
-: ash function format_dtg renamed to be
- string '''format_date_time(inFormat, dtg, outFormat)'''
- more info: http://kolmafia.us/showthread.php?8451-time_to_string()-with-parameter&p=64058&viewfull=1#post64058
- Modify examples on proxy record page because of:
+Do other installation steps as you wish.
-: Add the boolean "fancy" and "candy" fields to item '''proxy records'''.
-: Initial support for "Crimbo 2011" coinmaster: trade candy for Candy Credits
-: Add $skill '''proxy records''': .dailylimit and .timescast
-: Add a boolean "boss" field to $monster[]
-: Add the <s>"'''closet empty'''" CLI command, and</s> the '''empty_closet()''' ASH function.
+==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>
- r9181, 9183, 9184 & r9190: '''moods''' per slyz's summary here: http://kolmafia.us/showthread.php?8852-Composable-Moods
+Do every session:
- r10344 Add '''tavern( string goal )''' ASH function.
+# Navigate to your cloned repository: <pre>cd ~/projects/kolmafia</pre>
- goal can be "faucet", "baron", or  "explore" (to explore all remaining unexplored squares).
+# 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''.
- r10345 Add ASH '''tavern( "fight" )''' to explore cellar until the Baron's mansion is found
+# Compile KoLmafia with the Gradle wrapper: ''<syntaxhighlight lang="bash">./gradlew runShadow</syntaxhighlight>''
- and then go in to fight him.
- r10753-6 '''get_goals()''' returns a string[int] containing all the conditions that KoLmafia will
+=== Optional ===
- try to satisfy. Add g'''oal_exists()''' where you can pass in a goal type (choiceadv, autostop,
+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)]
- meat, health, mana, item) and KoLmafia will tell you if there are any goals that match.
+''[[Category:Tech Support]]''
- '''static''' scope is added!
- r10765: Add a "final" scope type to ASH which allows data/commands to be executed only
- once per session.
- r10772: A final declaration can either take a block, surrounded by {}, or a single
- command or declaration.
- r10774: ASH: "final" -> "static"
-: Add '''get_player_id()''' method to ASH
-: Add '''minstrel_quest()''' boolean function,
- which returns true when Clancy has a new quest for you.
-: Added boolean '''hippy_stone_broken()''' function
-: Make the CLI "attack" command work again. Make "pvp" equivalent to "steal" instead
- of "attack". Added "swagger" as equivalent to "flowers".
-: Added a 2-parameter version of '''to_string()''', where the first parameter can
- currently be an int or float (other types are possible, but didn't seem
- useful), and the second is a format string as defined by the Java
- String.format() method (which in turn is based on C printf() format strings).
- For example, "%.2f" will output a float with exactly two digits after the
- (localized) decimal point.
-: Add ASH function: '''pvp_attacks_left()'''. This is guaranteed accurate only if you
- have recently looked at the Fight! page. Tracking of PVP fights gained via
- consumption or familiar action and initialization at login will come later -
- after api.php is updated to include the figure.
- Add '''beforePVPScript''' setting which contains a script to be executed before a PVP
- attack. At the moment, this is only called from the Relay Browser - and only if
- relayRunsBeforePVPScript is true
-: Call beforePVPScript, if present, during automated PVP via the "flowers" command
-: Change ASH '''have_outfit()''' to work with custom outfits, as well as normal outfit
- Add ASH '''is_wearing_outfit()''' to return TRUE if you are currently wearing the
- specified custom or normal outfit.
-: Allow certain ASH constants to be used in custom combat settings.
- $phylum[] refers to the monster categorization, see the built-in ASH constants documentation for more information.
- $element[] refers to either the attack or the defense element. As long as one matches, this check will be satisfied. This may limit its usefulness, but we can evaluate it later.
- $item[] refers to an item that the monster drops. If there are multiple monsters that drop the item, or if you just can't remember which one it is, and your combat strategy happens to depend on it...
- In order to match, everything that you specify must match. So if you specify an impossible combination, that CCS section will not run.
- [ $element[ spooky ] $item[ hobo nickel ] ]
- skill entangling noodles
- skill weapon of the pastalord
- [ bathroom $element[ spooky ] ]
- attack
- [ $phylum[ beast ] ]
- skill stomp
- attack
-: new ASH functions:
- boolean '''is_familiar_equipment_locked()'''
- -returns true if current familiar equipment is locked, otherwise false
- void '''lock_familiar_equipment(boolean locking)'''
- -tries to lock/unlock fam equipment accordingly.
-: Add int '''get_clan_id()''' and string '''get_clan_name()''' functions.
-: Pass chat events along to '''chatbotscript'''. The sender is an empty string,
- the channel is "Events", and the message is stripped of its HTML.
-: Add '''is_discardable()''' which will return true even if an item can be autosold,
- so be careful you don't get cheated out of some meat.
-: Revert use of gift flag to previous interpretation: KoL has the item marked as
- a "Gift Item". Instead, change isGiftable() - which is also used by the ASH
- is_giftable() function - to allow either the "tradeable" or "gift" flags.
- Fix the item.gift proxy field to return the value of the gift flag, rather than
- being a synonym for is_giftable().
-: Add monster.raw_attack, monster.raw_defense, and monster.raw_hp to return the
- unmodified stats from monsters.txt.
-:  Add monster '''image_to_monster( string )''' ASH function for looking up monster by image file name.
- Add monster.image proxy field for going the other way.
-: experimental: add overloaded maximize() signature in ASH
- '''maximize( string maximizerString, int maxPrice, int priceLevel, boolean simulate, boolean showEquipment )'''
- returns an aggregate of records with each record containing the fields:
- **display => display text, as it is shown in the maximizer frame
- **cmd => actual command string that the maximizer runs to get the boost
- **score => the boost's score
- **effect => the effect provided by the boost - if applicable. effect[none] if it is equipment.
- **item => $item[] that is being suggested for use or equipment
- **skill => $skill[] that is being suggested
- If the showEquipment argument is false, equipment will be omitted from the results.
- r11707: Experimental ASH feature: the main() function of imported scripts can now be
- invoked, under the alternate name main@filename()
- (where 'filename' can be overridden by a 'script' directive, any ".ash"
- suffix is dropped, and non-alphanumeric characters are replaced by
- underscores). Note that no spaces are allowed around the @, the whole thing
- is a single token.
- r11965: Add my_companion()
- r11985: Add the "skeleton" CLI command.
- r12019: Add "eudora" CLI command
- r12060: add ASH get_moods(), returns an aggregate of currently defined mood names.
- "mood listall" in the gCLI will also print a list of defined moods.
- r12062: add ASH get_outfits() and get_custom_outfits()
- r12070: Overloaded version of appearance_rates considers monster queue:
- appearance_rates( $location[] location, boolean includeQueue )
- r12105: maximizerMRULength is now maximizerMRUSize
- That affects this page: [[Hidden_Features#Most_Recently_Used_Modifier_Maximizer_Expression]]
-== Needs Major Work ==
-[[Proxy Records]] is only slightly better than a placeholder.
- In r10047, the adventure tab interface was altered. Fix SinginSally's guide on pages...
- http://wiki.kolmafia.us/index.php?title=KoLmafia_Guide:_Attack_Script
- http://wiki.kolmafia.us/index.php?title=KoLmafia_Guide:_Custom_Combat_Script
- http://wiki.kolmafia.us/index.php?title=KoLmafia_Guide:_Goal-Oriented_Adventuring
- Information on moods calling other moods: http://kolmafia.us/showthread.php?8852-Composable-Moods&p=66468&viewfull=1#post66468
- r10025: Added '''choice''' CLI command, to resolve manual or unsupported choiceadventures
- Added "choice" CLI command, to resolve manual or unsupported choice
- adventures without having to visit the relay browser - which might be
- inconvenient if you're already in the CLI, and don't need to see the full
- adventure text to decide which option you want. With no parameter, "choice"
- just lists the options. With a numeric parameter, it picks that option.
- With any other parameter, it picks the first option containing that text (in
- either the actual button text, or mafia's spoiler text).
-== Needs Code Samples ==
-There is a list of all pages that require code samples: [[:Category:Needs_Code_Sample|Category:Needs Code Sample]]
-Information on how to create a code sample: [[Template:CodeSample]]