1. Setting up your IDE

To use ALox logging in your Java project, some few preparatory steps have to be taken.

Currently, there is no binary distribution of ALox for Java available. Therefore, the way to incorporate ALox into your project is to include the sources. There are two options:

add one of the existing ALox class library projects (Eclipse) to your solution, or
add ALox sources directly to your project.

Note: If you do not actually have a Java project (or do not want to touch one now) and you just want to have a first look into ALox, then create a new Java project in your IDE. Be sure to create an executable and that the typical "hello world" sample prints to the console.

1.1 Download

Unpack the ALox distribution (e.g. as zip) from Alox at GitHub and move all its contents to a place where you safely store 3rd party libraries.

We call this folder the ALOX_LIB_PATH. Within the folder you should find at least the following subfolders:

    ALOX_LIB_PATH\src.java
    ALOX_LIB_PATH\build
    ALOX_LIB_PATH\html

1.2. Eclipse

Predefined projects for Eclipse IDE (compatible with Luna, Mars, Neon, Oxygen, Photon) are found in

    ALOXLIBPATH/build/ide.java.eclipse

Note: The Java sources were coded using Eclipse with quite a high warning level setting. This led to the need to add some code annotations to suppress some warnings. If your Eclipse warning level setting is lower but now you get warnings on unnecessary code annotations (because the suppress warnings are not necessary in your environment), you can get rid of these messages by opening the Eclipse Preferences "Window/Preferences", Section "Java/Compiler/Errors/Warnings". Here, in the "Annotations" section, set "Unused '@SuppressWarnings' token:" to "Ignore".

1.3. Android Studio

Predefined projects for Android Studio are found in

    ALOXLIBPATH/build/ide.java.android-studio

The project includes a very basic sample, which is more or less a proof of concept.

1.4 Alternatively: Adding source code to your project

If there is no pre-defined project provided that suits your IDE (or needs), then you might want to add the ALox source code directly to your project or to a library project that you may want to create to separate the ALox code from your code. It should be fairly easy. The Java sources found in:

    ALOXLIBPATH/src.java/alib
    ALOXLIBPATH/src.java/alox

need to be compiled into your project.

Note: It is a good idea, to not copy the code, but to add the sources as links to their original place where you unpacked ALox. In Eclipse (Luna,Mars,Neon), linking source folders is found under "Project Properties", "Java Build Path", tab "Source" and then button "Link Source". The advantage of linking the source folders is that updating the source (e.g. with Git) updates them in your projects as well. Furthermore, if you might want to push your fixes or improvements to us using Git, the sources in the original folder need to be modified by you.

For Android, ALox provides a dedicated logger class that supports Android LogCat outputs. Therefore, to support Android projects, this logger class has to be added to your Android project (or Android ALox library project) into your project. For Android, in addition add folder:

    ALOXLIBPATH/src.java/alox.android

To stream ALox logging into LogCat create a logger of type AndroidLogCatLogger instead of type ConsoleLogger as follows:

Log.setVerbosity( new AndroidLogCatLogger(), Verbosity.VERBOSE );

Attention: The normal ConsoleLogger will not produce any visible output using the Android Emulator or a debugging device.

1.5 Test your setup

To test your setup, add minimum ALox functionality to your project as described in the first chapter of ALox for Java Tutorial into your main method or anywhere you think it is appropriate:

Log.info( "Hello ALox" );

You are set if:

your project compiles and runs without error and
you see the log output when running the debug version of your software.

In the next chapter it is explained how to remove this line of code automatically from "release" versions of your software.

Note: If the output line "Hello ALox" does not contain a "clickable link" that opens the editor with the line of source code that you just inserted, then you need to adjust the log output format. This is explained in a later chapter.

2. Pruning ALox Code in Java

2.1 What is Pruning?

An introduction to the concept of pruning is given in FAQ: What is Pruning?.

2.2 How Pruning in ALox for Java works

Unfortunately, Java does not provide conditional compiler statements. (For example, the languages C, C++ and C# allow #if ... #endif statements and C#, since Version 5, supports methods to be annotated to be pruned, which is very handy!)
Therefore, in Java we have to work with a tool that operates on the compiled class files and prunes everything that the tool is configured for in a separated release build step.
For this manual, we decided to work with ProGuard. The advantages that ProGuard offers are:

It is open source and free to use.
Well established in the industry and incorporated into various professional development platforms. It is also a part of the Android SDK. Therefore, Android developers have ProGuard already installed on their developer machines.
Besides pruning, ProGuard can be configured to obfuscate your code (see ProGuard FAQ).
Pruning is a part of the ProGuard optimization feature and these optimizations are very effective and beneficial for the performance of your application and the size (footprint) of your executable or library.

The disadvantages are:

A separated release built step has to be incorporated into your build process.
Due to the optimization features of ProGuard, the resulting code has to be tested extensively. (Sometimes ProGuard can corrupt your executable.)
If you choose to also obfuscate your code (not needed for pruning!) then debugging the release versions of your software gets very tough. Also stack traces from exceptions are only readable using a dedicated ProGuard tool.

2.3 What to Prune

There are two possible configurations that differ in the breadth of pruning:

Pruning with release logging enabled
This is the configuration you need if just your debug Log Statements are to be pruned. Use this, if you use ALox to perform some release logging.
Pruning all ALox code
This is the configuration you need to prune just all ALox code out of your library or executable. Use this, if you exclusively use ALox for debug logging purposes.

Note: For quick information on the terms "debug and release logging", read the FAQ.

2.3.1 ProGuard configuration for different platforms

Depending on your Java target platform, choose one of the following subchapters to read further:

Note

The configuration provided here was tested with

ProGuard Version 4.11, release, Dec. 2013
ProGuard Version 5.2, released Jan 2015

2.3.2 ProGuard configuration for standard Java

In the distribution folder of ALox, you will find a sample project in subfolder:

    ALOX_LIB_PATH/build/ide.java.eclipse/ALox-Java-1.6-Test

Within this folder, you will find the different ProGuard sample configuration files:

For pruning just the debug logging statements and enable release logging:
```
  proguard-prune-alox-debug.pro
```
For pruning ALox completely:
```
  proguard-prune-alox-all.pro
```

Both files have the same start:

### input/output ###
-injars ../ALox-Java-1.6/bin
-injars bin/ALoxSamples.class
-outjars bin.pruned
 
### for testing ###
#-verbose
#-printusage
#-dontobfuscate
 
-optimizationpasses 5
 
-keepclasseswithmembers public class ALoxSamples
{
    public static void main(java.lang.String[]);
}
 
# Pruning AWorx Library assertions and debug messages
-assumenosideeffects    class   com.aworx.lib.ALIB_DBG     { <methods>;  <fields>; }

For your own projects, you have to modify the first lines starting with

    -injars...

to include your project code and library projects Then, the configuration that only prunes debug logging but leaves release logging in, continues as follows:

# Pruning ALOX debug logging (release logging stays in)

-assumenosideeffects class com.aworx.lox.Log { <methods>; <fields>; }

The other configuration file, that prunes just all ALox stuff continues like this:

# Pruning ALOX completely (release logging as well as debug logging)

-assumenosideeffects class com.aworx.lox.* { <methods>; <fields>; }

Both files then continue with other default ProGuard configuration code.

Note: You can configure ProGuard the way you prefer, however, you must not disable the optimization step, as this is where ProGuard prunes ALox!

Note: ProGuard supports Ant Tasks and Gradle Tasks. See the corresponding ProGuard documentation for details.

That all, you are set!

The test project distributed with ALox can be easily used to see what is happening using ProGuard. Go ahead as follows:

Add the following two projects to Eclipse (or compile them with your favorite IDE):

  ALOX_LIB_PATH/build/ide.java.eclipse/ALox-Java-1.6_ (if not done, yet)
  ALOX_LIB_PATH/build/ide.java.eclipse/ALox-Java-1.6-Test

Make sure you have ProGuard installed (if you have Android SDK installed, you have ProGuard!)
It may be necessary to set the PROGUARD_HOME environment variable to the ProGuard path, e.g.
```
  PROGUARD_HOME=c:\\usr\\Dev\\Android\\android-sdk\\tools\\proguard
```
Open a command prompt (Windows) respectively a shell window (Linux)
It may be necessary to set the JAVA_HOME environment variable to your Java JDK or JRE, e.g.
```
  JAVA_HOME=C:\\Program Files\\Java\\jre6 (Windows OS)
  JAVA_HOME=/lib/jvm/java-7-openjdk/jre/  (Arch Linux)
```

cd into:

  ALOX_LIB_PATH/build/ide.java.eclipse/ALox-Java-1.6-Test

Launch
```
  ./Samples.[sh|bat]
```
and check the un-pruned output of the test

Launch

  ./proguard-prune-alox-debug.[sh|bat]
  ./Samples-Pruned.[sh|bat]

and check the output of the test with debug logging pruned

Launch

  ./proguard-prune-alox-all.[sh|bat]
  ./Samples-Pruned.[sh|bat]

and check the output of the test with all logging pruned

Note: If you look into the script files that invoke ProGuard (proguard-prune-alox-debug.[sh|bat] and proguard-prune-alox-all.[sh|bat]) you will see that the Java runtime library is passed as another parameter. This parameter might be moved into the *.pro configuration files as well. To have them here, seems more appropriate, as this way, the current Java environment activated on your machine is used.

2.3.3 ProGuard configuration for Android

As ProGuard is a part of the Android SDK, there is plenty of documentation and help found in the internet on how to configure ProGuard and how the post compilation step is included into the build system. A good start to read more deatils on this is found here: http://developer.android.com/tools/help/proguard.html.

But the setup if fairly easy! On a fresh, new Android project (in Eclipse) the steps that have to be taken are the following:

We start editing the file project.properties, found the root folder of your Eclipse project. At the end of the file, add the following lines:

# proguard

proguard.config=${sdk.dir}/tools/proguard/proguard-android-optimize.txt:proguard-project.txt

Note: While the Android SDK documentation (see link above) does not really talk to much about it, the SDK provides an extended basic configuration file for ProGuard, that enables optimization of class files, hence enables pruning of ALox.
Next, we edit the file proguard-project.txt, also found the root folder of your Eclipse project.
- If you want to enable release logging, at the end of the file, add the following lines:
  
  # Pruning ALox debug logging (release logging stays in)
  
  -assumenosideeffects class com.aworx.lox.Log { <methods>; <fields>; }
- Alternatively, if you want to disable release logging (prune all ALox logging from your code), at the end of the file, add the following lines:
  
  # Pruning ALox completely (release logging as well as debug logging)
  
  -assumenosideeffects class com.aworx.lox.** { <methods>; <fields>; }

Note: Of-course you can also leave debug logging enabled in your release android app and still use ProGuard as intended by the Android SDK. For this, just do not put any of the above lines in the proguard-project.txt file.

This is all you need to do!

When "exporting" your application into an APK file, ALox gets automatically pruned by ProGuard and the Android SDK build process.

ALox provides a preconfigured sample project for Android:

Add the two following two projects to Eclipse (or compile them with your favorite IDE):

_ALOX_LIB_PATH/build/ide.java.eclipse/ALox-Java-Android (if not done, yet)
_ALOX_LIB_PATH/build/ide.java.eclipse/ALox-Java-Android-Test-Release-Log

You can export the APK file of the latter project in two variants: with release logging enabled or disabled. Modify proguard-project.txt accordingly and see what happens when you launch the APK on your device.

Also, you might want to have a quick look this projects sample code found in:

ALOX_LIB_PATH/build/ide.java.eclipse/ALox-Java-Android-Test-Release-Log/src/com/aworx/alox_java_android_test_release_log/ALoxJavaAndroidTestReleaseLog.java

to get a first understanding of ALox release logging.

2.4 Obfuscating the code

As mentioned already, ProGuard provides an optional feature to obfuscate your code. Again, this is only optional and obfuscation has benefits but also some disadvantages. In respect to ALox, obfuscation introduces one little difficulty related to all methods that work with the "caller scope". Most remarkably, most Scope Domain setting will stop working, because packages, class names and file names get mangled heavily.
The implication is, that any release logging statements (debug log is not affected as this is either way pruned from your release binaries) must not use Scope Domains. In other words, for each invocation of a log call (again, only of release logging!) the Log Domain has to be explicitly set.

For release logging in combination with obfuscation, you might want to suppress the output of scope information in the log line (see TextLogger.metaInfo for information on how to do that).

On the same token, the methods Lox.setDomain, Lox.store/ retrieve and Lox.once will not work properly with language-related Scopes if you obfuscate. For more information on this, refer to the user manual chapters about Scope Domains, Scopes and features building on Scopes.

Finally, it is obvious that LogTools.instance() will not show readable results when your classes become obfuscated.

2.5 Mission accomplished: Perfect Auto Pruning of ALox code!

The result of the things said above incorporate six great news for you:

You can safely use all methods of classes Log and LogTools without any special treatment for pruning within your code.
The impact of using ALox debug Log Statements in respect to execution speed in the release version of your application is exactly ZERO, because the methods do not make it into your release executable!
The impact of using ALox in respect to the footprint of your executable extremely small (all that remains are some empty classes with a few stubs). This remains true, even if thousands of new features would come in future versions of ALox!
All debug Log Statements, including all textual messages you are adding to your log calls, are completely pruned from the release executable! Your "debug secrets" can not be reverse engineered, they are just gone!
Even if you mix debug and release logging features of ALox the above stays true, except that the footprint of the ALox library is a little higher.

Note: This is all true for Java. For other platforms check out platform specific sections of ALox pruning techniques.

Note: The Android SDK documentation suggests to "remove all your logging code" releasing an Android app. From now on you can just ignore this advice!

3. Tweaking The Log Output

In addition to setting up the project, the format of the log output of ALox should be recognizable by your IDE: the source code file name and line number that generated the output should become "clickable" in the log: It should link back to the source in the editor.

While different IDEs have different abilities and syntax for that, unfortunately, there are some IDEs that do not support such "clickable log output" at all.
This chapter gives some tips for different IDEs. We hope that the IDE you are using is listed here and it supports this feature. Otherwise, it may need a little testing, maybe some trial and error process, to see how the output needs to be done to be properly consumed by your IDE.

3.1 Eclipse

While the eclipse application output pane "Console" does not support colorful output (e.g. ANSI code), Java file names and line numbers of of log statements are recognized by Eclipse in a reliable way.

Therefore, these or similar configuration variable settings are recommended:

[ALOX]
CONSOLE_TYPE=         plain
DEBUG_LOGGER_FORMAT=  "(%SF:%SL) %SM():%A5[%TC +%TL][%tN]%V[%D]%A1(%#): ",    \
                      [ERR],                                                  \
                      [WRN],                                                  \
                      "     ",                                                \
                      [***]

3.2 IntelliJ IDEA

JetBrains IntelliJ IDEA has an intelligent output console that supports ANSI colors and detects links to files when they are given in the right format.

However, there are some specialties to know:

The java source file name and line number need to be in brackets and prefixed with a dot. The format is .(source.java:NNN)
Within a line that contains the link, no other number which is followed by a closing bracket might appear. By default, ALox shows the current log number in brackets. This has to be changed.
No light ANSI colors are supported Therefore, the use of light colors has to be switched off. If this is not done, colors are in most cases not effective.

As a summary, these or similar configuration variable settings are recommended:

[ALOX]
CONSOLE_TYPE=           ANSI
CONSOLE_LIGHT_COLORS=   never
DEBUG_LOGGER_FORMAT=    .(%SF:%SL) %SM():%A5[%TC +%TL][%tN][%D]%A1#%#:%V,     \
                        \e[31m,                                               \
                        \e[34m,                                               \
                        "     ",                                              \
                        \e[33m

Table of Contents