gjp 0.32.0 → 0.33.0

data/MOTIVATION.md

@@ -0,0 +1,27 @@
+# Motivation
+
+The Java developer world has packages (jars, wars, ears...), tools ([ant](http://ant.apache.org/), [Maven](http://maven.apache.org/), [Ivy](http://ant.apache.org/ivy/), [Gradle](http://www.gradle.org/)...) and established workflows to handle software distribution while Linux distros have their own ([zypper](http://en.opensuse.org/Portal:Zypper), [yum](http://en.wikipedia.org/wiki/Yellowdog_Updater,_Modified), [apt](http://en.wikipedia.org/wiki/Advanced_Packaging_Tool)...). Since the two communities have different goals and requirements, Linux distros typically want to repackage Java software with their own format, tools and workflows. Reasons range from ease of installation, predictable rebuildability, support to (security) patching, management tools, legal issues, etc.
+
+Unfortunately those two "schemes" became very different over time, so automatic translation/repackaging is not possible except in very simple cases. This leads to a lot of tedious, error-prone manual work that Linux packagers have to do in order to fit the "alien" Java model into distro packaging rules that were thought and optimized with a different ecosystem in mind.
+
+A typical example is packaging any software built by Maven on SUSE distros. A number of pain points arise:
+
+* Maven requires Internet access and downloads precompiled code as part of the build. RPMs have to be built on a standalone machine in [OBS](http://en.opensuse.org/openSUSE:Build_Service), and they should build code from sources they are provided beforehands exclusively;
+* [Maven is basically a plugin container](http://maven.apache.org/plugins/), so hundreds of different plugins have to be installed to build real-life projects (the exact plugin set and their dependencies is determined at build time). While this is no big deal for Java developers, since they get the corresponding jars prebuilt from public Intenet Maven repositories, it is a nightmare for distros, because all shipping code is supposed to be built from scratch and packaged!
+* Maven often uses multiple versions of a same library or plugin during the same build. Usually distros do not accept more than one version of any given library to reduce maintenance work;
+* Maven requires itself in order to build. To be more exact, Maven needs Nexus, which in turn needs Maven and Nexus. To be more exact, its build dependency graph is a very complicated mess with lots of cycles that have to be broken manually.
+
+The current solution in openSUSE is having the packager handle those differences, but this limits the amount of software the community is able to package due to the high effort required to overcome them.
+
+The Fedora community is experimenting with another set of tools, [XMvn](http://mizdebsk.fedorapeople.org/xmvn/site/), which goals are similar to `gjp`'s. 
+
+## Kit rationale
+
+`gjp` simplifies the packaging process mostly because of its use of a binary blob package that contains all build time dependencies for a set of packages called a **kit**.
+
+Building software from a binary blob is unusual for Linux distros, and it surely has some drawbacks. It is anyway believed that benefits outweigh them, in fact using prebuilt software:
+
+* drastically reduces packaging efforts. A very basic and relatively simple package like [commons-collections](http://commons.apache.org/proper/commons-collections/) needs about [150 jars](https://build.opensuse.org/package/show/home:SilvioMoioli/myproject-kit) just to be compiled and tested. Those should be packaged, roughly, one-by-one!
+* is just the way all Java developers out there build, test and use their software — this is how they expect it to work. Any different approach is necessarily error-prone and could result in unexpected bugs;
+* does not affect the ability of providing patches to Java projects, as only build time requirements are in the kit. In virtually all cases patching a piece of software does not require to patch its build toolchain;
+* does not affect the ability of complying to software licenses like the GPL. In fact those licenses only require to redistribute a project's source code - not the whole toolchain needed to build it. Sources can be added and shipped together with binaries when licenses require it.

data/README.md

@@ -1,39 +1,39 @@
-# gjp – Green Java Packager's tools
+# gjp – builds RPMs for Java software
 
-`gjp` is a set of tools to ease creating Linux packages for Java projects.
-
-## Why?
+`gjp` is a set of tools to help you build RPM packages for Java projects.
 
 Packaging of Java projects is sometimes hard because build tools like Maven partially overlap with distro tools like RPM in functionality.
 
 We are trying to come up with **a tool that drastically simplifies packaging**.
 
-## How to install?
+## Installation
 
-First you need:
+You need:
 
 * [Ruby 1.9](https://www.ruby-lang.org/en/);
 * [git](http://git-scm.com/);
 * a JDK that can compile whatever software you need to package;
-* only for the optional `set-up-nonet-user` subcommand, `sudo` and `iptables`.
 
-You can install gjp via RubyGems:
+Install `gjp` via RubyGems:
 
-    $ gem install gjp
+     gem install gjp
 
 ## Workflow
 
-Building a package with `gjp` is quite unusual — this is a [deliberate choice](#motivation), so don't worry. Basic steps are:
+Building a package with `gjp` is quite unusual — this is a deliberate choice, so don't worry. Basic steps are:
 
 * `gjp init` a new project;
-* add sources to `src/<package name>` and everything else you need in binary form in `kit/` (eg. a Maven binary distribution);
-* execute `gjp dry-run`, any command needed to compile your software (possibly `gjp mvn package`), then `gjp finish`;
-* execute `gjp generate-all`;
-* done! Spec files and tarballs are baked in `output` automatically by `gjp`.
+* add sources to `src/<package name>` and anything else needed for the build in `kit/` in binary form (typically a copy of Maven and maybe some other dependency jars);
+* execute `gjp dry-run`, then any command needed to compile your software, then `gjp finish`;
+* execute `gjp generate-all`: gjp will look at changed files and Bash history to scaffold spec files and tarballs.
+
+Done!
 
-## How can that possibly work? (commons-collections walkthrough)
+### How can that possibly work?
 
-Let's review all steps in detail with a concrete Maven-based example, commons-collections.
+With `gjp` you are not building all dependencies from source, just your package. Everything else is shipped already compiled with attached source files, which is much easier to implement and automate. Yet, it is sufficient to fulfill open source licenses and to have a repeatable, networkless build. See [MOTIVATION.md](MOTIVATION.md) for further information.
+
+## A commons-collections walkthrough
 
 First, ceate a new `gjp` project, in this example named "myproject":
 
@@ -41,9 +41,7 @@ First, ceate a new `gjp` project, in this example named "myproject":
     cd myproject
     gjp init
 
-(`gjp init` generates a folder structure for you).
-
-Second, place all your projects' source files in `src/`. Every `src/` subfolder will become a separate package named after the folder itself, so use the following commands to create a `commons-collections` folders and populate it:
+Second, place commons-collections source files in the `src/` folder. Specifically, every `src/` subfolder will become a separate package named after the folder itself, so you can use the following:
 
     cd src
     mkdir commons-collections
@@ -52,167 +50,34 @@ Second, place all your projects' source files in `src/`. Every `src/` subfolder
     unzip commons-collections-3.2.1-src.zip
     rm commons-collections-3.2.1-src.zip
 
-Third, all non-source files needed for the build should go into `kit`. This includes all build dependencies and tools excluding the JDK, so in this case we need Maven:
+Third, put all non-source files needed for the build in `kit/`. This means all build dependencies and tools excluding the JDK: in this case it is just Maven:
 
     cd ../../kit
     wget http://www.eu.apache.org/dist/maven/binaries/apache-maven-3.1.1-bin.zip
     unzip apache-maven-3.1.1-bin.zip
     rm apache-maven-3.1.1-bin.zip
 
-Fourth, you need to show `gjp` how to build your package by executing `gjp dry-run` and `gjp finish`. Bash history will be recorded to generate a build script (possibly only a starting point, maybe sufficient in simple cases):
+Fourth, you need to show `gjp` how to build your package by running appropriate commands between `gjp dry-run` and `gjp finish`. Bash history will be recorded to generate a "starting-point" build script (that will be sufficient in simple cases like this):
 
+    cd ../src/commons-collections/commons-collections-3.2.1-src/
     gjp dry-run
-    cd src/commons-collections/commons-collections-3.2.1-src/
     gjp mvn package
     gjp finish
 
-Note that we used `gjp mvn package` instead of `mvn package` so that `gjp` will use Maven from `kit/` instead of the system-wide installation you might have. `gjp` will also add some options on the mvn commandline so that any downloaded files will be retained in `kit/m2` so that this build can be replayed (even without network access) later. Also note that this being a dry-run build, sources will be brought back to their original state after `gjp finish`. This ensures build repeatability.
+Note that we used `gjp mvn package` instead of `mvn package`: this will use of the Maven copy we put in `kit/` and the repository in `kit/m2`.
+Also note that this being a dry-run build, sources will be brought back to their original state after `gjp finish`, as this ensures build repeatability.
 
-Finally, use this command to let `gjp` to generate build scripts, spec files and tarballs:
+Finally, generate build scripts, spec files and tarballs in the `output/` directory:
 
     gjp generate-all
 
-Note that gjp will also generate a special binary-only package called a **kit**, which contains basically the `kit/` folder. This is the only build-time requirement of any `gjp` package in your project.
-
-## Special cases
-
-### Failing builds
-
-If youyr build fails for whatever reason, abort it with `gjp finish --abort`. `gjp` will restore all project files as they were before build.
-
-### Manual changes
-
-You can do any manual changes to spec and build.sh files and regenerate them later, `gjp` will reconcile changes with a [three-way merge](http://en.wikipedia.org/wiki/Three-way_merge#Three-way_merge) and alert about any conflicts. You can generate single files with the following commands:
-
-* `gjp generate-kit-archive`: (re)generates the kit tarball;
-* `gjp generate-kit-spec`: (re)generates the kit spec;
-* `gjp generate-package-script`: (re)generates the `build.sh` file from the latest bash history (assumes `gjp dry-run` and `gjp finish`have been used). Assumes your current working directory is in a package folder (that is, a subdirectory of `src/<package name>/`);
-* `gjp generate-package-archive`: (re)generates a package tarball;
-* `gjp generate-package-spec`: (re)generates a package spec;
-
-Note that, by default, `generate-kit-archive` will generate additional "diff" tar.xz files instead of rewriting the whole archive - this will result in faster uploads if you use OBS (see below). You can use the `--full` option to regenerate a single complete archive.
-
-### [OBS](build.opensuse.org)
-
-If you want to submit packages to OBS, you can do so by replacing the `output/` directory in your `gjp` project with a symlink to your OBS project directory.
-
-Packages will rebuild cleanly in OBS because no Internet access is needed - all files were already downloaded during dry-run and are included in the kit.
-
-Note that the kit package is needed at build time only by OBS, no end user should ever install it.
-
-### Kit sources
-
-Your kit is basically a binary blob. If its sources are needed for proper packaging, for example to comply with the GPL, some extra steps are needed.
-
-If you use Maven, most (~90%) sources can be automatically downloaded:
-
-    gjp get-maven-source-jars
-
-The remaining (mostly very outdated) jars will be listed by `gjp` when the download ends. You need to manually find corresponding sources for them, you can use:
-
-    gjp get-source /path/to/<jar name>.pom
-
-to get pointers to relevant sites if available in the pom itself.
-
-A list of commonly used jars can be found [below](#frequently-used-sources).
-
-You can also use:
-
-    gjp list-kit-missing-sources
-
-To get a list of jars that have one or more `.class` file which does not have a corresponding `.java` file in `kit/` (or zip files in `kit/`).
-
-### Ant builds
-
-`gjp` is currently optimized for Maven as it is the most common build tool, but it can work with any other. In particular, support for Ant has already been implemented and `gjp ant` works like `gjp mvn`.
+Note that `gjp` will generate files for the commons-collections package and for the binary-only myproject-kit package, which is a special container of all build-time dependencies (basically, the `kit/` folder). This will be shared among all packages you might add to your `gjp` project.
 
-Sometimes you will have jar files distributed along with the source archive that will end up in `src/`: you don't want that! Run
+## In-depth information
 
-    gjp purge-jars
+In more complex cases building a package will require some special tweaks. We are trying to cover the most common in the [SPECIAL_CASES.md](SPECIAL_CASES.md) file.
 
-to have them moved to `kit/jars`. The command will generate a symlink back to the original, so builds will work as expected.
-
-When generating spec files, be sure to have a `pom.xml` in your package directory even if you are not using Maven: `gjp` will automatically take advantage of information from it to compile many fields.
-
-You can also ask `gjp` to find one via `gjp get-pom <filename>.jar` (be sure to have Maven in your kit).
-
-### Other builds
-
-Other build tools are currently unsupported but will be added in the future. You can nevertheless use them - the only rule is that you have to keep all of their files in `kit`.
-
-### Optional: networkless dry-run builds
-
-If you want to be 100% sure your package builds without network access, you can use a special `gjp` subcommand to setup a `nonet` user that cannot use the Internet. Then you can simply retry the build using that user to see if it works. Note that the following commands will alter group permissions to allow both your current user and `nonet` to work on the same files.
-
-    gjp set-up-nonet-user
-    chmod -R g+rw ../../..
-    gjp dry-run
-    su nonet
-    ping www.google.com #this should fail!
-    gjp mvn package
-    chmod -R g+rw .
-    exit
-    gjp finish
-
-### Gotchas
-
-* `gjp` internally uses `git` to keep track of files, any gjp project is actually also a `git` repo. Feel free to navigate it, you can commit, push and pull as long as the `gjp` tags are preserved. You can also delete commits and tags, effectively rewinding gjp history (just make sure to delete all tags pointing to a certain commit when you discard it);
-* if your sources come from a Git repo, be sure to remove any `.git`/`.gitignore` files, otherwise `gjp` might get confused;
-* if OBS complains that jars in your kit or package are compiled for a JDK version higher than 1.5, add the following line after `%install` to squelch the error:
-
-    export NO_BRP_CHECK_BYTECODE_VERSION=true
-
-* if packages build at first but then fail after a few days because Maven tries to connect to the Internet, add the `--option` flag to the `mvn` line in `build.sh`;
-
-### Frequently used sources
-
-* antlr-2.7.7: `wget http://www.antlr2.org/download/antlr-2.7.7.tar.gz -O kit/m2/antlr/antlr/2.7.7/antlr-2.7.7-sources.tar.gz`;
-* ant-launcher-1.6.5: sources included in ant-1.6.5;
-* asm-3.3.1: `wget http://download.forge.ow2.org/asm/asm-3.3.1.tar.gz -O kit/m2/asm/asm/3.3.1/asm-3.3.1-sources.tar.gz`;
-* jsr305-1.3.9: sources included in jar;
-* jsr305-2.0.1: sources included in jar;
-* commons-lang-1.0: `wget http://archive.apache.org/dist/commons/lang/source/lang-1.0-src.tar.gz -O kit/m2/commons-lang/commons-lang/1.0/commons-lang-1.0-sources.tar.gz`;
-* commons-logging-api-1.1: `wget http://archive.apache.org/dist/commons/logging/source/commons-logging-1.1-src.tar.gz -O kit/m2/commons-logging/commons-logging/1.1/commons-logging-1.1-sources.tar.gz` (included in commons-logging-1.1);
-* commons-logging-1.0: `wget http://archive.apache.org/dist/commons/logging/source/commons-logging-1.0-src.tar.gz -O kit/m2/commons-logging/commons-logging/1.0/commons-logging-1.0-sources.tar.gz`;
-* dom4j-1.1: `wget http://dom4j.cvs.sourceforge.net/viewvc/dom4j/dom4j/?view=tar&pathrev=dom4j-1-1 -O kit/m2/dom4j/dom4j/1.1/dom4j-1.1-sources.tar.gz`;
-* doxia-sink-api-1.0-alpha-4: use `svn export http://svn.apache.org/repos/asf/maven/doxia/doxia/tags/doxia-sink-api-1.0-alpha-4/ kit/m2/doxia/doxia-sink-api/1.0-alpha-4/doxia-sink-api-1.0-alpha-4-sources`;
-* kxml2-2.2.2: use `wget http://sourceforge.net/projects/kxml/files/kxml2/2.2.2/kxml2-src-2.2.2.zip/download -O kit/m2/net/sf/kxml/kxml2/2.2.2/kxml2-2.2.2-sources.zip`;
-* log4j-1.2.12: `wget http://archive.apache.org/dist/logging/log4j/1.2.12/logging-log4j-1.2.12.tar.gz -O kit/m2/log4j/log4j/1.2.12/log4j-1.2.12-sources.tar.gz`;
-* stringtemplate-3.2: `wget http://www.stringtemplate.org/download/stringtemplate-3.2.tar.gz -O kit/m2/org/antlr/stringtemplate/3.2/stringtemplate-3.2-sources.tar.gz`;
-* velocity-tools-2.0: `wget http://archive.apache.org/dist/velocity/tools/2.0/velocity-tools-2.0-src.tar.gz -O kit/m2/org/apache/velocity/velocity-tools/2.0/velocity-tools-2.0-sources.tar.gz`;
-* velocity-1.5: `wget http://archive.apache.org/dist/velocity/engine/1.5/velocity-1.5.tar.gz -O kit/m2/org/apache/velocity/velocity/1.5/velocity-1.5-sources.tar.gz`;
-* trilead-ssh2-build213-svnkit-1.3: `svn export http://svn.svnkit.com/repos/svnkit/tags/1.3.5/ kit/m2/org/tmatesoft/svnkit/svnkit/1.3.5/svnkit-1.3.5-sources` (included in svnkit 1.3.5 full sources because of custom patch);
-* xercesImpl-2.9.1: `wget http://archive.apache.org/dist/xerces/j/source/Xerces-J-src.2.9.1.tar.gz -O kit/m2/xerces/xercesImpl/2.9.1/xercesImpl-2.9.1-sources.tar.gz`;
-* xmlpull-1.1.3.1: wget `http://www.extreme.indiana.edu/xmlpull-website/v1/download/xmlpull_1_1_3_4c_src.tgz -O kit/m2/xmlpull/xmlpull/1.1.3.1/xmlpull-1.1.3.1-sources.tar.gz`
-* xmlunit-1.3: `wget http://sourceforge.net/projects/xmlunit/files/xmlunit%20for%20Java/XMLUnit%20for%20Java%201.3/xmlunit-1.3-src.zip/download -O kit/m2/xmlunit/xmlunit/1.3/xmlunit-1.3-sources.zip`;
-
-## Motivation
-
-The Java developer world has packages (jars, wars, ears...), tools ([ant](http://ant.apache.org/), [Maven](http://maven.apache.org/), [Ivy](http://ant.apache.org/ivy/), [Gradle](http://www.gradle.org/)...) and established workflows to handle software distribution while Linux distros have their own ([zypper](http://en.opensuse.org/Portal:Zypper), [yum](http://en.wikipedia.org/wiki/Yellowdog_Updater,_Modified), [apt](http://en.wikipedia.org/wiki/Advanced_Packaging_Tool)...). Since the two communities have different goals and requirements, Linux distros typically want to repackage Java software with their own format, tools and workflows. Reasons range from ease of installation, predictable rebuildability, support to (security) patching, management tools, legal issues, etc.
-
-Unfortunately those two "schemes" became very different over time, so automatic translation/repackaging is not possible except in very simple cases. This leads to a lot of tedious, error-prone manual work that Linux packagers have to do in order to fit the "alien" Java model into distro packaging rules that were thought and optimized with a different ecosystem in mind.
-
-A typical example is packaging any software built by Maven on SUSE distros. A number of pain points arise:
-
-* Maven requires Internet access and downloads precompiled code as part of the build. RPMs have to be built on a standalone machine in [OBS](http://en.opensuse.org/openSUSE:Build_Service), and they should build code from sources they are provided beforehands exclusively;
-* [Maven is basically a plugin container](http://maven.apache.org/plugins/), so hundreds of different plugins have to be installed to build real-life projects (the exact plugin set and their dependencies is determined at build time). While this is no big deal for Java developers, since they get the corresponding jars prebuilt from Maven itself, it is a nightmare for distros, because all shipping code is supposed to be built from scratch and packaged!
-* Maven often uses multiple versions of a same library or plugin during the same build. Usually distros do not maintain more than one version of any given library to reduce maintenance;
-* Maven requires itself in order to build. To be more exact, Maven needs Nexus, which in turn needs Maven and Nexus. To be more exact, its build dependency graph is a very complicated mess with lots of cycles that have to be broken manually.
-
-The current solution in openSUSE is having the packager handle those differences, but this limits the amount of software the community is able to package due to the high effort required to overcome them.
-
-The Fedora community is experimenting with another set of tools, [XMvn](http://mizdebsk.fedorapeople.org/xmvn/site/), which goals are similar to `gjp`'s. 
-
-## Kit rationale
-
-`gjp` simplifies the packaging process mostly because of its use of a binary blob package that contains all build time dependencies for a set of packages called a **kit**.
-
-Building software from a binary blob is unusual for Linux distros, and it surely has some drawbacks. It is anyway believed that benefits outweigh them, in fact using prebuilt software:
-
-* drastically reduces packaging efforts. A very basic and relatively simple package like [commons-collections](http://commons.apache.org/proper/commons-collections/) needs about [150 jars](https://build.opensuse.org/package/show/home:SilvioMoioli/myproject-kit) just to be compiled and tested. Those should be packaged, roughly, one-by-one!
-* is just the way all Java developers out there build, test and use their software — this is how they expect it to work. Any different approach is necessarily error-prone and could result in unexpected bugs;
-* does not affect the ability of providing patches to Java projects, as only build time requirements are in the kit. In virtually all cases patching a piece of software does not require to patch its build toolchain;
-* does not affect the ability of complying to software licenses like the GPL. In fact those licenses only require to redistribute a project's source code - not the whole toolchain needed to build it. [Sources can be added](#kit-sources) for GPL'd parts of the kit, if any.
+An in-depth discussion of this project's motivation is available in the [MOTIVATION.md](MOTIVATION.md) file.
 
 ## Status
 
@@ -220,7 +85,6 @@ Building software from a binary blob is unusual for Linux distros, and it surely
 
 At the moment `gjp` is tested on openSUSE.
 
-
 ## Sources
 
 `gjp`'s Git repo is available on GitHub, which can be browsed at:

data/SPECIAL_CASES.md

@@ -0,0 +1,126 @@
+# Special cases
+
+## Failing builds
+
+If your build fails for whatever reason, abort it with `gjp finish --abort`. `gjp` will restore all project files as they were before build.
+
+## Manual changes to generated files
+
+You can do any manual changes to spec and build.sh files and regenerate them later, `gjp` will reconcile changes with a [three-way merge](http://en.wikipedia.org/wiki/Three-way_merge#Three-way_merge) and alert about any conflicts. You can generate single files with the following commands:
+
+* `gjp generate-kit-archive`: (re)generates the kit tarball;
+* `gjp generate-kit-spec`: (re)generates the kit spec;
+* `gjp generate-package-script`: (re)generates the `build.sh` file from the latest bash history (assumes `gjp dry-run` and `gjp finish`have been used). Assumes your current working directory is in a package folder (that is, a subdirectory of `src/<package name>/`);
+* `gjp generate-package-archive`: (re)generates a package tarball;
+* `gjp generate-package-spec`: (re)generates a package spec;
+
+Note that, by default, `generate-kit-archive` will generate additional "diff" tar.xz files instead of rewriting the whole archive - this will result in faster uploads if you use OBS (see below). You can use the `--full` option to regenerate a single complete archive.
+
+## Kit sources
+
+Your kit is basically a binary blob. If its sources are needed for proper packaging, for example to comply with the GPL, some extra steps are needed.
+
+If you use Maven, most (~90%) sources can be automatically downloaded:
+
+    gjp download-maven-source-jars
+
+The remaining (mostly very outdated) jars will be listed by `gjp` when the download ends. You need to manually find corresponding sources for them, you can use:
+
+    gjp get-source /path/to/<jar name>.pom
+
+to get pointers to relevant sites if available in the pom itself.
+
+A list of commonly used jars can be found [below](#frequently-used-sources).
+
+You can also use:
+
+    gjp list-kit-missing-sources
+
+To get a list of jars that have one or more `.class` file which does not have a corresponding `.java` file in `kit/` (or zip files in `kit/`).
+
+## Ant builds
+
+`gjp` is currently optimized for Maven as it is the most common build tool, but it can work with any other. In particular, support for Ant has already been implemented and `gjp ant` works like `gjp mvn`.
+
+Sometimes you will have jar files distributed along with the source archive that will end up in `src/`: you don't want that! Run
+
+    gjp move-jars-to-kit
+
+to have them moved to `kit/jars`. The command will generate a symlink back to the original, so builds will work as expected.
+
+When generating spec files, be sure to have a `pom.xml` in your package directory even if you are not using Maven: `gjp` will automatically take advantage of information from it to compile many fields.
+
+You can also ask `gjp` to find one via `gjp get-pom <filename>.jar` (be sure to have Maven in your kit).
+
+## Other build tools
+
+Other build tools are currently unsupported but will be added in the future. You can nevertheless use them - the only rule is that you have to keep all of their files in `kit`.
+
+## [OBS](build.opensuse.org) integration
+
+If you want to submit packages to OBS, you can do so by replacing the `output/` directory in your `gjp` project with a symlink to your OBS project directory.
+
+Packages will rebuild cleanly in OBS because no Internet access is needed - all files were already downloaded during dry-run and are included in the kit.
+
+Note that the kit package is needed at build time only by OBS, no end user should ever install it.
+
+
+## Gotchas
+
+* `gjp` internally uses `git` to keep track of files, any gjp project is actually also a `git` repo. Feel free to navigate it, you can commit, push and pull as long as the `gjp` tags are preserved. You can also delete commits and tags, effectively rewinding gjp history (just make sure to delete all tags pointing to a certain commit when you discard it);
+* if your sources come from a Git repo, be sure to remove any `.git`/`.gitignore` files, otherwise `gjp` might get confused;
+* if OBS complains that jars in your kit or package are compiled for a JDK version higher than 1.5, add the following line after `%install` to squelch the error:
+
+    export NO_BRP_CHECK_BYTECODE_VERSION=true
+
+* if packages build at first but then fail after a few days because Maven tries to connect to the Internet, add the `--option` flag to the `mvn` line in `build.sh`;
+* if you want to be 100% sure your package builds without network access, you can use scripts in the `utils/` folder to create a special `nonet` user that cannot use the Internet and retry the build from that user.
+
+## Frequently used sources
+
+* ant-1.8.1: `wget http://archive.apache.org/dist/ant/source/apache-ant-1.8.1-src.tar.gz -O kit/m2/org/apache/ant/ant/1.8.1/ant-1.8.1-sources.tar.gz`;
+* ant-1.8.2: `wget http://archive.apache.org/dist/ant/source/apache-ant-1.8.2-src.tar.gz -O kit/m2/org/apache/ant/ant/1.8.2/ant-1.8.2-sources.tar.gz`;
+* ant-launcher-<version>: sources included in ant-<version>;
+* ant-nodeps-<version>: sources included in ant-<version>;
+* antlr-2.7.7: `wget http://www.antlr2.org/download/antlr-2.7.7.tar.gz -O kit/m2/antlr/antlr/2.7.7/antlr-2.7.7-sources.tar.gz`;
+* asm-3.3.1, asm-commons-3.3.1, asm-tree-3.3.1: `wget http://download.forge.ow2.org/asm/asm-3.3.1.tar.gz -O kit/m2/asm/asm/3.3.1/asm-3.3.1-sources.tar.gz`;
+* aspectjrt-1.5.3: `wget http://git.eclipse.org/c/aspectj/org.aspectj.git/snapshot/org.aspectj-1_5_3_final.tar.gz -O kit/m2/aspectj/aspectjrt/1.5.3/aspectjrt-1.5.3-sources.tar.gz` (you can remove tests, lib, docs and org.eclipse.jdt.core);
+* avalon-framework-4.1.5: `wget http://archive.apache.org/dist/avalon/avalon-framework/v4.1.5/avalon-framework-4.1.5.src.tar.gz -O kit/m2/avalon-framework/avalon-framework/4.1.5//4.1.5--sources.tar.gz`;
+* batik-<subartifact>-1.7: `mkdir kit/m2/org/apache/xmlgraphics/batik/; wget http://archive.apache.org/dist/xmlgraphics/batik/batik-src-1.7.zip -O kit/m2/org/apache/xmlgraphics/batik/batik-sources.zip`
+* bndlib-0.0.238, bndlib-0.0.255: these are used by apache-felix-1.4.x, which is in turn used by commons-parent < 22 to provide JDK 1.4 compatibility. Unfortunately no source before 1.1 is available, if possible update your dependencies to commons-parent >= 22;
+* bsh-2.0b4: `wget http://beanshell2.googlecode.com/files/bsh-2.0b4-src.jar -O kit/m2/org/beanshell/bsh/2.0b4/bsh-2.0b4-sources.zip`;
+* commons-beanutils-core-1.8.0: `wget http://archive.apache.org/dist/commons/beanutils/source/commons-beanutils-1.8.0-src.tar.gz -O kit/m2/commons-beanutils/commons-beanutils-core/1.8.0/commons-beanutils-core-1.8.0-sources.tar.gz`;
+* commons-beanutils-core-1.8.3: `wget http://archive.apache.org/dist/commons/beanutils/source/commons-beanutils-1.8.3-src.tar.gz -O kit/m2/commons-beanutils/commons-beanutils-core/1.8.3/commons-beanutils-core-1.8.3-sources.tar.gz`;
+* commons-codec-1.2: `wget http://archive.apache.org/dist/commons/codec/source/commons-codec-1.2-src.tar.gz -O kit/m2/commons-codec/commons-codec/1.2/commons-codec-1.2-sources.tar.gz`;
+* commons-collections-testframework-3.2.1: included in commons-collections-3.2.1;
+* commons-collections-2.0: `wget http://archive.apache.org/dist/commons/collections/source/collections-2.0-src.tar.gz -O kit/m2/commons-collections/commons-collections/2.0/commons-collections-2.0-sources.tar.gz`;
+* commons-jexl-1.1: `wget http://archive.apache.org/dist/commons/jexl/source/commons-jexl-1.1-src.tar.gz -O kit/m2/commons-jexl/commons-jexl/1.1/commons-jexl-1.1-sources.tar.gz`;
+* commons-lang-1.0: `wget http://archive.apache.org/dist/commons/lang/source/lang-1.0-src.tar.gz -O kit/m2/commons-lang/commons-lang/1.0/commons-lang-1.0-sources.tar.gz`;
+* commons-logging-api-1.1: `wget http://archive.apache.org/dist/commons/logging/source/commons-logging-1.1-src.tar.gz -O kit/m2/commons-logging/commons-logging/1.1/commons-logging-1.1-sources.tar.gz` (included in commons-logging-1.1);
+* commons-logging-1.0: `wget http://archive.apache.org/dist/commons/logging/source/logging-1.0-src.tar.gz -O kit/m2/commons-logging/commons-logging/1.0/commons-logging-1.0-sources.tar.gz`;
+* derby-10.9.1.0: `wget http://archive.apache.org/dist/db/derby/db-derby-10.9.1.0/db-derby-10.9.1.0-src.tar.gz -O kit/m2/org/apache/derby/derby/10.9.1.0/derby-10.9.1.0-sources.tar.gz`;
+* dom4j-1.1: `wget http://dom4j.cvs.sourceforge.net/viewvc/dom4j/dom4j/?view=tar\&pathrev=dom4j-1-1 -O kit/m2/dom4j/dom4j/1.1/dom4j-1.1-sources.tar.gz`;
+* doxia-sink-api-1.0-alpha-4: use `svn export http://svn.apache.org/repos/asf/maven/doxia/doxia/tags/doxia-sink-api-1.0-alpha-4/ kit/m2/doxia/doxia-sink-api/1.0-alpha-4/doxia-sink-api-1.0-alpha-4-sources`;
+* fop-0.95: `wget http://archive.apache.org/dist/xmlgraphics/fop/source/fop-0.95-src.tar.gz -O kit/m2/org/apache/xmlgraphics/fop/0.95/fop-0.95-sources.tar.gz`;
+* hc-stylecheck-1: contains only metadata, no sources to be compiled in this artifact;
+* jsr305-1.3.9, jsr305-2.0.1: sources included in jar;
+* jsch-0.1.38: `wget http://sourceforge.net/projects/jsch/files/jsch/0.1.38/jsch-0.1.38.zip/download -O kit/m2/com/jcraft/jsch/0.1.38/jsch-0.1.38-sources.zip`;
+* kxml2-2.2.2: use `wget http://sourceforge.net/projects/kxml/files/kxml2/2.2.2/kxml2-src-2.2.2.zip/download -O kit/m2/net/sf/kxml/kxml2/2.2.2/kxml2-2.2.2-sources.zip`;
+* log4j-1.2.12: `wget http://archive.apache.org/dist/logging/log4j/1.2.12/logging-log4j-1.2.12.tar.gz -O kit/m2/log4j/log4j/1.2.12/log4j-1.2.12-sources.tar.gz`;
+* naming-common-5.0.28, naming-java-5.0.28: `mkdir -p kit/m2/tomcat/tomcat/5.0.28/; wget http://archive.apache.org/dist/tomcat/tomcat-5/v5.0.28/src/jakarta-tomcat-5.0.28-src.tar.gz -O kit/m2/tomcat/tomcat/5.0.28/tomcat-5.0.28-sources.tar.gz` (part of tomcat);
+* org.osgi.core-1.0.0: `wget http://archive.apache.org/dist/felix/org.osgi.core-1.0.0.tar.gz -O kit/m2/org/apache/felix/org.osgi.core/1.0.0/org.osgi.core-1.0.0-sources.tar.gz`;
+* org.osgi.core-4.1.0: sources included in jar;
+* org.osgi.service.obr-1.0.1: `wget http://archive.apache.org/dist/felix/org.osgi.service.obr-1.0.1-project.tar.gz -O kit/m2/org/apache/felix/org.osgi.service.obr/1.0.1/org.osgi.service.obr-1.0.1-sources.tar.gz`;
+* plexus-utils-1.4.9: `wget https://github.com/sonatype/plexus-utils/archive/plexus-utils-1.4.9.tar.gz -O kit/m2/org/codehaus/plexus/plexus-utils/1.4.9/plexus-utils-1.4.9-sources.tar.gz`;
+* spymemcached-2.6: `wget http://spymemcached.googlecode.com/files/memcached-2.4.2-sources.zip -O kit/m2/spy/spymemcached/2.6/spymemcached-2.6-sources.zip`;
+* stringtemplate-3.2: `wget http://www.stringtemplate.org/download/stringtemplate-3.2.tar.gz -O kit/m2/org/antlr/stringtemplate/3.2/stringtemplate-3.2-sources.tar.gz`;
+* velocity-tools-2.0: `wget http://archive.apache.org/dist/velocity/tools/2.0/velocity-tools-2.0-src.tar.gz -O kit/m2/org/apache/velocity/velocity-tools/2.0/velocity-tools-2.0-sources.tar.gz`;
+* velocity-1.5: `wget http://archive.apache.org/dist/velocity/engine/1.5/velocity-1.5.tar.gz -O kit/m2/org/apache/velocity/velocity/1.5/velocity-1.5-sources.tar.gz`;
+* trilead-ssh2-build213-svnkit-1.3: `svn export http://svn.svnkit.com/repos/svnkit/tags/1.3.5/ kit/m2/org/tmatesoft/svnkit/svnkit/1.3.5/svnkit-1.3.5-sources` (included in svnkit 1.3.5 full sources because of custom patch);
+* xercesImpl-2.9.1: `wget http://archive.apache.org/dist/xerces/j/source/Xerces-J-src.2.9.1.tar.gz -O kit/m2/xerces/xercesImpl/2.9.1/xercesImpl-2.9.1-sources.tar.gz`;
+* xercesMinimal-1.9.6.2: included in any xercesImpl >= 2 source package;
+* xml-apis-ext-1.3.04: `wget http://archive.apache.org/dist/xml/commons/xml-commons-external-1.3.04-src.tar.gz -O kit/m2/xml-apis/xml-apis-ext/1.3.04/xml-apis-ext-1.3.04-sources.tar.gz`;
+* xmlgraphics-commons-1.3.1: `wget http://archive.apache.org/dist/xmlgraphics/commons/source/xmlgraphics-commons-1.3.1-src.tar.gz -O kit/m2/org/apache/xmlgraphics/xmlgraphics-commons/1.3.1/xmlgraphics-commons-1.3.1-sources.tar.gz`;
+* xmlpull-1.1.3.1: `wget http://www.extreme.indiana.edu/xmlpull-website/v1/download/xmlpull_1_1_3_4c_src.tgz -O kit/m2/xmlpull/xmlpull/1.1.3.1/xmlpull-1.1.3.1-sources.tar.gz`;
+* xpp3-1.1.3.3: `wget http://www.extreme.indiana.edu/dist/java-repository/xpp3/distributions/xpp3-1.1.3.4.C_src.tgz -O kit/m2/xpp3/xpp3/1.1.3.3/xpp3-1.1.3.3-sources.tar.gz`;
+* xmlunit-1.3: `wget http://sourceforge.net/projects/xmlunit/files/xmlunit%20for%20Java/XMLUnit%20for%20Java%201.3/xmlunit-1.3-src.zip/download -O kit/m2/xmlunit/xmlunit/1.3/xmlunit-1.3-sources.zip`;

data/lib/gjp.rb

@@ -7,7 +7,6 @@ require "gjp/project"
 require "gjp/pom"
 require "gjp/version_matcher"
 require "gjp/maven_website"
-require "gjp/limited_network_user"
 require "gjp/pom_getter"
 require "gjp/source_getter"
 require "gjp/kit_runner"

data/lib/gjp/cli.rb

@@ -215,7 +215,7 @@ module Gjp
       end
     end
 
-    subcommand "purge-jars", "Locates jars in src/ and moves them to kit/" do
+    subcommand "move-jars-to-kit", "Locates jars in src/ and moves them to kit/" do
       def execute
         checking_exceptions do
           project = Gjp::Project.new(".")
@@ -229,7 +229,7 @@ module Gjp
       end
     end
 
-    subcommand "get-maven-source-jars", "Attempts to download Maven kit/ sources" do
+    subcommand "download-maven-source-jars", "Attempts to download Maven kit/ sources" do
       def execute
         checking_exceptions do
           project = Gjp::Project.new(".")
@@ -254,34 +254,6 @@ module Gjp
       end
     end
 
-    subcommand "set-up-nonet-user", "Sets up a \"nonet\" user that cannot access the network" do
-      def execute
-        checking_exceptions do
-          user = Gjp::LimitedNetworkUser.new("nonet")
-          user.set_up
-
-          "sudo #{user.get_path("useradd")} nonet\n" +
-          "sudo #{user.get_path("iptables")} -A OUTPUT -m owner --uid-owner nonet -j DROP\n" +
-          "User \"nonet\" set up, you can use \"sudo nonet\" to dry-run your build with no network access.\n" +
-          "Note that the above iptables rule will be cleared at next reboot, you can use your distribution " +
-          "tools to make it persistent or run \"gjp set-up-limited-nertwork-user\" again next time."
-        end
-      end
-    end
-
-    subcommand "tear-down-nonet-user", "Deletes a user previously created by gjp" do
-      def execute
-        checking_exceptions do
-          user = Gjp::LimitedNetworkUser.new("nonet")
-
-          user.tear_down
-
-          "sudo #{user.get_path("iptables")} -D OUTPUT -m owner --uid-owner nonet -j DROP\n" +
-          "sudo #{user.get_path("userdel")} nonet\n"
-        end
-      end
-    end
-
     subcommand "get-pom", "Retrieves a pom file" do
       parameter "NAME", "a jar file name or a `name-version` string (heuristic)"
       def execute

data/lib/gjp/version.rb

@@ -1,5 +1,5 @@
 # encoding: UTF-8
 
 module Gjp
-  VERSION = "0.32.0"
+  VERSION = "0.33.0"
 end

data/utils/delete_nonet_user.sh

@@ -0,0 +1,8 @@
+#!/bin/bash
+
+su
+useradd nonet
+passwd nonet
+
+iptables -A OUTPUT -m owner --uid-owner nonet -j DROP
+

data/utils/setup_nonet_user.sh

@@ -0,0 +1,8 @@
+#!/bin/bash
+
+su
+useradd nonet
+passwd nonet
+
+iptables -A OUTPUT -m owner --uid-owner nonet -j DROP
+

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gjp
 version: !ruby/object:Gem::Version
-  version: 0.32.0
+  version: 0.33.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-12-31 00:00:00.000000000 Z
+date: 2014-01-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -151,8 +151,10 @@ files:
 - Gemfile
 - Gemfile.lock
 - LICENSE
+- MOTIVATION.md
 - README.md
 - Rakefile
+- SPECIAL_CASES.md
 - bin/gjp
 - gjp.gemspec
 - integration-tests/commons.sh
@@ -164,7 +166,6 @@ files:
 - lib/gjp/kit_checker.rb
 - lib/gjp/kit_runner.rb
 - lib/gjp/kit_spec_adapter.rb
-- lib/gjp/limited_network_user.rb
 - lib/gjp/logger.rb
 - lib/gjp/maven_runner.rb
 - lib/gjp/maven_website.rb
@@ -207,7 +208,6 @@ files:
 - spec/lib/git_spec.rb
 - spec/lib/kit_checker_spec.rb
 - spec/lib/kit_runner_spec.rb
-- spec/lib/limited_network_user_spec_interactive.rb
 - spec/lib/maven_runner_spec.rb
 - spec/lib/maven_website_spec.rb
 - spec/lib/pom_getter_spec.rb
@@ -219,6 +219,8 @@ files:
 - spec/lib/template_manager_spec.rb
 - spec/lib/version_matcher_spec.rb
 - spec/spec_helper.rb
+- utils/delete_nonet_user.sh
+- utils/setup_nonet_user.sh
 homepage: https://github.com/SilvioMoioli/gjp
 licenses:
 - MIT
@@ -266,7 +268,6 @@ test_files:
 - spec/lib/git_spec.rb
 - spec/lib/kit_checker_spec.rb
 - spec/lib/kit_runner_spec.rb
-- spec/lib/limited_network_user_spec_interactive.rb
 - spec/lib/maven_runner_spec.rb
 - spec/lib/maven_website_spec.rb
 - spec/lib/pom_getter_spec.rb

data/lib/gjp/limited_network_user.rb

@@ -1,64 +0,0 @@
-# encoding: UTF-8
-
-require 'find'
-
-module Gjp
-  # encapsulates a Linux user that cannot access the Internet
-  # assumes root access (sudo) and iptables are available
-  class LimitedNetworkUser
-    include Logger
-
-    def initialize(name)
-      @name = name
-    end
-
-    # creates a new Linux user without Internet access,
-    # if it does not exists
-    def set_up
-      log.debug "checking #{@name} user existence..."
-      if not user_exists?
-        log.debug "...not found. Setting up..."
-        `sudo #{get_path("useradd")} #{@name}`
-        `sudo #{get_path("passwd")} #{@name}`
-        log.debug "...set up"
-      end
-
-      if not firewall_rule_exists?
-        log.debug "...not found. Setting up..."
-        `sudo #{get_path("iptables")} -A OUTPUT -m owner --uid-owner #{@name} -j DROP`
-        log.debug "...set up"
-      end
-    end
-
-    # deletes a Linux user previously created by this class
-    def tear_down
-      if firewall_rule_exists?
-        `sudo #{get_path("iptables")} -D OUTPUT -m owner --uid-owner #{@name} -j DROP`
-      end
-
-      if user_exists?
-        `sudo #{get_path("userdel")} #{@name}`
-      end
-    end
-
-    # determines if a user without Internet access exists
-    def set_up?
-      user_exists? && firewall_rule_exists?
-    end
-
-    # checks user existence
-    def user_exists?
-      `id #{@name} 2>&1`.match(/no such user$/) == nil
-    end
-
-    # checks firewall rule existence
-    def firewall_rule_exists?
-      `sudo #{get_path("iptables")} -L`.match(/owner UID match #{@name}/) != nil
-    end
-
-    # returns a command's full path
-    def get_path(command)
-      `sudo which #{command}`.strip
-    end
-  end
-end

data/spec/lib/limited_network_user_spec_interactive.rb

@@ -1,39 +0,0 @@
-# encoding: UTF-8
-
-require 'spec_helper'
-
-describe Gjp::LimitedNetworkUser do
-  let(:user) { Gjp::LimitedNetworkUser.new("nonet_test") }
-
-  before(:each)  do
-    user.set_up
-  end
-
-  after(:each)  do
-    if user.set_up?
-      user.tear_down
-    end
-  end
-
-  describe "#set_up" do
-    it "set_ups a limited network user" do
-      user.set_up?.should be_true
-    end
-  end
-
-  describe "#tear_down" do
-    it "tears down a limited network user" do
-      user.tear_down
-      user.set_up?.should be_false
-    end
-  end
-
-  describe "#set_up?" do
-    it "checks if a limited network user has been set up" do
-      user.set_up?.should be_true
-
-      user.tear_down
-      user.set_up?.should be_false
-    end
-  end
-end