From 2cffda6974c8f62a427935bcdbd1e96fa1d3723b Mon Sep 17 00:00:00 2001 From: idk <hankhill19580@gmail.com> Date: Thu, 10 Dec 2020 13:42:02 -0500 Subject: [PATCH] update the HACKING.md to reflect better and/or git-based instructions, also a test commit for git migration. --- docs/HACKING.md | 129 +++++++++++++++++++++++++++++++------ docs/MONOTONECHEATSHEET.md | 5 -- 2 files changed, 109 insertions(+), 25 deletions(-) diff --git a/docs/HACKING.md b/docs/HACKING.md index c16cf1a4d5..51b49efab2 100644 --- a/docs/HACKING.md +++ b/docs/HACKING.md @@ -1,37 +1,126 @@ # Readme for hacking on the source ## Build systems -The build system of I2P today is a bit mixed. -In the old days, and at least for relasing we actually use -the old `ant` tool. For the new Browser Bundle launcher, as -well as the Mac OSX launcher the `sbt` tool from the Scala -world was used cause it gives some increadibly effictive plugins -and logic to build them while keeping a relation to the old build -system. -We also have Gradle partly implemented, much work, but not all. Meeh -which is writing this readme is guessing we'll end up with a combination -of Gradle and SBT in the end when we know what kind of structure we want. +### Release/Core Packages build system: Ant +To build the I2P java packages we use the Apache `ant` build system. +If you need to build a complete I2P installer for all platforms, run +the: + + ant pkg + +target, which will produce `jar` and `exe` files. If you are a developer +who already has I2P installed, it is convenient to build updater packages +instead of the whole installer to speed up builds and to avoid needing to +repeatedly re-run the installer. To simply build the updater `zip` files, +run: + + ant updater + +then copy the updater to the I2P configuration directory and re-start I2P. +On Linux, this is `$HOME/.i2p` if you installed with the `install.jar` file, and +on Windows it is `%LOCALAPPDATA%\I2P\`. When using Debian packages, this type +of update is intentionally disabled so that the application can be updated from +the repositories securely. If you are a Debian user who wants to temporarily +try out a dev build, the easiest way is to run: + + sudo systemctl stop i2p + +or + + sudo service i2p stop + +to stop the I2P Service started by the package, then use an `install.jar` to +set up an I2P Package as your user. Then, run: + + ~/i2p/i2prouter start + +to start the user-installed I2P service. This version of I2P will also be able to +use an updater `zip` file to update itself. When you're done using your dev build, +you can run: + + ~/i2p/i2prouter stop + +then run: + + sudo systemctl start i2p + +or + + sudo service i2p start + +### Peripheral/External Packages: SBT + +The (Discontinued)Browser Bundle launcher, as well as the Mac OSX +launcher the `sbt` tool from the Scala project is actually used +underneath, but the `sbt` can still be executed by an `ant` target. +To build the OSX launcher, run the: + + ant osxLauncher + +target, and to build the Browser Bundle launcher, run the: + + ant bbLauncher + +target. ## Browsing around the source code If you're new at this, which we all was at one point, I'll have some tips. -* Check out our [DIRECTORIES.md](DIRECTORIES.md) to learn ore -about where you'll find I2P's different parts in the codebase. +* The [DIRECTORIES.md](DIRECTORIES.md) contains a listing of the directories +in the I2P source code and what the code inside them is used for. + +* Some parts of the I2P router are started by files that end with the suffix +`'Runner.java'` and can be listed by running the command +`find . -type f -name '*Runner.java'` in the root of your `i2p.i2p` source +directory. + +## The ... ~~Monotone~~ part + +Monotone served I2P well for many many years, but it's deprecated now. Instead, +we're using Git like almost everybody else. + +Please join us at: [https://i2pgit.org](https://i2pgit.org) +and [http://git.idk.i2p](http://git.idk.i2p). -* For me (Meeh), it worked well to run `find . -type f -name '*Runner.java'` -from the source tree root, and take a look at the files that get listed. A lot -of hints of how this is peaced together lies there. +If you're used to monotone and need to see how common monotone commands relate +to git equivalents, the [MONOTONECHEATSHEET.md](MONOTONECHEATSHEET.md) may be +a relevant reference. +## Git clone depth and Git Bundles -## The .. Monotone part +Since `git` is not resumable until a repository is cloned, it is helpful to obtain +the copies of of i2p.i2p anonymously in one of a couple ways to make the initial clone +process more reliable. There are two ways to obtain a git repository reliably over I2P +first, configure your git client according to the instructions on the [I2P Project Site](https://geti2p.net/en/docs/applications/git) +and clone -Check out [MONOTONECHEATSHEET.md](MONOTONECHEATSHEET.md) file. + git clone --depth 1 git@127.0.0.1:i2p-hackers/i2p.i2p + +This will clone the minimum amount of i2p.i2p to have a working checkout. You can then +resumably populate the repository with the remaining commits by running: + + git fetch --unshallow + +in the newly-created `i2p.i2p` directory. + +You can also obtain a historical copy of the i2p.i2p source code from a git bundle which +is distributed as a torrent. Instructions for doing this are also on the [I2P Project Site](https://geti2p.net/en/docs/applications/git-bundle). +Once obtained, you can "clone" using the bundle, then `git remote set-url origin git@127.0.0.1:i2p-hackers/i2p.i2p` +to configure it to use the upstream git remote. Finally, run + + git fetch --all + +to finish updating your source code. ## SBT Behind proxy -Seems it's a hassle behind SOCKSv5. But for use of HTTP proxy to fetch -dependencies and such, please edit `export SBT_OPTS="$SBT_OPTS -Dhttp.proxyHost=myproxy-Dhttp.proxyPort=myport"` -to have correct values for your system, then execute it before you start SBT. +`sbt` does not work well with SOCKS5 proxies. In order to use it with Tor, +you will need to use an HTTP Proxy in-between. You can configure an HTTP Proxy +for `sbt` with the SBT_OPTS environment variable. + + export SBT_OPTS="$SBT_OPTS -Dhttp.proxyHost=myproxy-Dhttp.proxyPort=myport" + +by setting it before you start `sbt`. diff --git a/docs/MONOTONECHEATSHEET.md b/docs/MONOTONECHEATSHEET.md index a56d94052a..fc3900e8ee 100644 --- a/docs/MONOTONECHEATSHEET.md +++ b/docs/MONOTONECHEATSHEET.md @@ -1,7 +1,5 @@ # Monotone cheatsheet -**Slogan:** *Saving you hours reading old manuals* - For most of us developers using git, one of the columns will have an example of how certain things are done in git, to easier know what to do in monotone. @@ -20,9 +18,6 @@ Command | Git cmd (which give same info) | Description `mtn list tag` | `git tag -l` | List tags in the repo. `mtn di -r t:TAGNAME` | `git diff TAGNAME` | Show you the diff between the choosen tag and current head. -TBA... - -Contributions are welcome! -- GitLab