Before you can build and run ActivityLog2 you will need to install Racket. This can be downloaded from "http://racket-lang.org/". ActivityLog2 is build and tested using the latest Racket version and previous versions may or may not work.
For creating a Windows installer, see the documentation in the scripts folder, this is not needed if you only want to build and run the application on your local machine.
ActivityLog2 uses web services for some of the functionality. Currently, Thunderforest is used for map tiles. These services require API keys to access them. The built (and released) version of the application has these API keys embedded in the executable, however the keys are kept separate from the code base.
ActivityLog2 will work without these API keys, however, only OpenStreetMap map tiles will be available.
You will need to obtain your own API keys, if you wish to build your own application. To use these keys, you need to set two environment variables:
AL2TFAPIKEY-- contains the API key for Thunderforest maps
These environment variables will be used while ActivityLog2 is running during development and they will also be embedded in any built executable.
ActivityLog2 depends on some additional packages and the official ActivityLog2 build has these under version control in the "pkgs/" sub-folder and will need to be installed before building or running the application. Once installed these packages will be available for all Racket programs (Unfortunately, Racket has no concept of virtual environments for packages.)
You don't need to install dependencies as outlined below. If you want, you
can install the following packages directly from the racket package catalog:
tzinfo, tzgeolookup, data-frame, plot-container, gui-widget-mixins,
map-widget and al2-test-runner (for running the tests). If you go this
route, you may not have the exact versions which are used by ActivityLog2, and
may encounter problems.
Update Submodules after you cloned this repository, you will need to update the submodules using the commands:
git submodule update --init --recursive
Setup Package Catalog next, you will need to add the "pkgs/" sub-folder to
the list of Racket catalogs by running the command below (bash is available
on Windows as part of the git installation):
bash etc/scripts/setup-catalog.sh pkgs/
Install Dependencies Once the catalog is set up, you will need to install dependencies:
raco pkg install --auto al2-dependencies
Build Or Run the Application Once the packages are set up, you can run the
application using the following command (you can also open the run.rkt file
in DrRacket and run it from within the IDE):
racket run.rkt
... or build the ActivityLog2 executable and an installer using the following command:
racket build.rkt
This command will create a stand-alone application in the "dist" folder and this application will run even on machines that don't have Racket installed. If you have Inno setup installed and are on Windows, the above command will also create an installer executable.
Each ActivityLog2 release is tagged, you can check the tag names using the
command git tag -l in a checked out source and use git log tag-1..tag-2 to
find the detailed changes between two tags. For example to find the changes
between version 1.7.1 and 1.8.0 you can run:
git log v1.7.1..v1.8.0
Or, if you want to see what has changed in each submodule as well:
git log --submodule=log --patch v1.10.2..v1.11 \
| awk '/^commit/,/^diff/ { if ($1 != "diff") { print; } }'`
You can separate the build steps if you open the file "build.rkt" in DrRacket, run it by clicking the "Run" button or pressing "Ctrl-R", than type the following expressions in the interactions window:
(compile-app) ; builds ZO files from the Racket source files
(build-app) ; creates the ActivityLog2 executable
(mkdist) ; packages the executable and required files into the dist folder
While working on the source code, it might be worth compiling the files first to speed things up:
raco make run.rkt rkt/main.rkt
Note that if compiled files are present, racket will not re-compile modified files, you will need to recompile them explicitly, otherwise you will encounter load errors when trying to run ActivityLog2.
This application uses git submodules to track dependent packages and git provides detailed documentation for working with sub-modules, and this will not be repeated here, but here are a few important points to consider after changing branches, or pulling in new commits from a remote branch, in case the dependent modules have changed or new modules have been added:
- Run
git submodule syncto setup any new modules - Run
git submodule updateto obtain the version of the submodules referenced by the current branch - Run the
etc/scripts/setup-catalog.shscript again to re-build the package catalog - Run
raco pkg update --deps search-auto al2-dependenciesto install any new modules - Run
raco pkg setupto re-build any files in dependent packages (will make compilation and startup faster)
Which commands you need to run depends on what has changed, and requires some experience.
- database.md describes how data is stored and used by the application
- xdata.md describes how XDATA (Garmin IQ data) is stored and used by the application.
- data-frame.md describes the data frame structure which is used inside the application to store data from sessions and other types of data.
- session-df.md describes the contents of a data frame containing session data.
- gui-consistency.md describes how various GUI parts communicate changes between each other.
- hrv-notes.md describes how to access HRV data in FIT files.
- segment-df.md describes the contents of the data frame object containing a GPS Segment.
The application uses the MAJOR.MINOR.PATCH.BUILD versioning scheme, where:
MAJORrepresents the major version number, which should increment only on a major application re-write (I don't expect that to happen.)MINORrepresents the minor version number, and it increments when new features are added, or existing features are changed/updatedPATCHincrements for bug-fixes, the special value "99" indicates an unreleased version (e.g. 1.8.99)BUILDis the Azure pipelines build id, and should be a unique number which always increments for every Azure build, regardless of the other numbers.
The file "version.txt" contains the current version number, without the BUILD part (e.g. 1.8.99), and the build script picks up the version from this file -- when changing version numbers, this is the only file that should change.
ActivityLog2 has a test suite, this runs on Azure Pipelines, each time data is pushed to a branch or a pull request is created. The main aim of the test suite is to ensure that the application builds and packages cleanly and that the data storage and basic data operations work.
Tests can also be run manually using commands such as:
raco test test/db-test.rkt
raco test test/df-test.rkt
Some tests require data that is private and you will not be able to run them
-- these tests run automatically on Azure Pipelines. For the list of all the
tests and how to run them, see the test/ folder and the
azure-pipelines.yml build file.
Some features can be enabled manually to help debug the application, they can
be enabled by running a Racket program such as using "al-interactive.rkt" and
using put-pref (and get-pref to obtain their state):
(require "al-interactive.rkt")
(put-pref 'activity-log:debug:show-stop-points? #t)The following options are defined:
activity-log:debug:show-stop-points?-- when set to#t, the session graphs and elevation graph on map view will show vertical lines for stop points (blue) and teleport points (red). See session-df.md for the meaning of these.
ActivityLog2 uses a log file to record various debug information while it
runs. On a Windows machine, the log file is located in
"%APPDATA%/Local/ActivityLog/ActivityLogDbg.log", for other platforms, see
maybe-init-log-port in rkt/utilities.rkt. It is
worth consulting this file when trying to diagnose problems as it usually
contains more information than what it just reported to the user using the
GUI.
When ActivityLog2 throws an exception it can be logged in two places: the console or the log file and exceptions thrown from separate threads will usually be logged to the log file.
The dbglog, dbglog-exception and thread/dbglog functions, defined in
"rtk/utilities.rkt" can also be used to add additional logging as needed.
By default, the exceptions that are logged will not contain a stack trace and it may be difficult to identify where an exception occurred. To enable stack traces in exceptions, first remove all your compiled files from the "compiled" folders, than run the command below. This will take a long time to load and will run slow:
racket -l errortrace -t run.rkt
Using the traceld library will print out all the modules that are loaded,
along with a timestamp. This can be used to determine where is the time spent
when loading and instantiating modules:
racket -l mzlib/traceld -t run.rkt
The al2-profiler package contains definitions which
allow tracing individual function calls. It is more practical than the
"trace" module shipped with Racket, as it allows to explicitly specify which
functions to trace. To use it, require the "al-profiler.rkt" module and
replace define calls with define/trace calls. This also works for method
names, where define/public can be replaced with define/public/trace.
The al2-profiler module also contains a small profiler, see that file for more details.
This package is not installed by default, you can install it using
raco pkg install al2-profiler
or, if you didn't setup the package catalog using
rack pkg install ./pkgs/al2-profiler