diff --git a/README.md b/README.md index be4af28..de433a2 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,7 @@ Multi-platform "Fast Log Entry"(FLE) processing tool. ![Go Build & Test](https://github.com/jmMeessen/FLEcli/workflows/Go%20Build%20&%20Test/badge.svg) +[![codecov](https://codecov.io/gh/on4kjm/FLEcli/branch/master/graph/badge.svg)](https://codecov.io/gh/on4kjm/FLEcli) ["Fast Log Entry"](https://www.df3cb.com/fle/) is a nifty tool, written by DF3CB. It allows quick and efficient entry of radio amateur contacts made during DXpeditions, contests or SOTA/WWFF activation. It can export the listed contacts in ADIF format ready to be uploaded to eQSL/LOTW or submitted for SOTA and WWFF. The program is only available as a Windows executable which leaves the Mac or Linux users (like me) in the cold. @@ -9,96 +10,30 @@ This tool is intended to process FLE formatted files on other platform than Wind But is also the alibi to learn and explore GO. -## Usage +------ -### Installing -The tool is installed by downloading and unpacking the archive for your operating system. -The releases are downloaded for https://github.com/on4kjm/FLEcli/releases +## Installing +The tool is installed by downloading and unpacking the archive for your operating system. -The application is available in the following packaging: -* `FLEcli_v..._macOS_64-bit.tar.gz` is the MacOS version. -* `FLEcli_v..._windows_32-bit.zip` is the Windows version. Only the 32 bit is proposed as it should work also on older Windows version. -* `FLEcli_v..._Linux_64-bit.tar.gz` is the 64 bits distribution for Linux. -* `FLEcli_v..._Linux_32-bit.tar.gz` is the 32 bits distribution for Linux -* `FLEcli_v..._Linux_arm.tar.gz` is the 32 bits ARM (instruction set 6) distribution (for RaspberryPi older models for example) -* `FLEcli_v..._Linux_arm64.tar.gz` is the 64 bits ARM (instruction set 6) distribution +A version is available for Windows, MacOS, Linux and ARM (RaspeberyPi). +Most of them are available as 32 or 64 bit applications. +A docker version is also available. -Detailed installation instructions can be found here (TODO). +The releases can be downloaded from https://github.com/on4kjm/FLEcli/releases -**Important note:** at this stage, the MacOS binary is not signed. It will fail to load on the recent OS version unless a very permissive security setting is enable (which is not advised). Therefore, it is advised to run FLEcli as a Docker application (available on DockerHub). An alternative is to compile the application. Further explanation can be found here (TODO) +Detailed installation instructions can be found [at this page](doc/install.md). -### Commands and options -``` -Usage: - FLEcli [command] - -Available Commands: - adif Generates an ADIF file based on a FLE type shorthand logfile. - csv Generates a SOTA .csv file based on a FLE type shorthand logfile. - help Help about any command - load Loads and validates a FLE type shorthand logfile - version "version" will output the current build information +## Usage -Flags: - --config string config file (default is $HOME/.FLEcli.yaml) - -h, --help help for FLEcli +Detailed explanations can be found [on this page](doc/usage.md). -Use "FLEcli [command] --help" for more information about a command. ------- -FLEcli load --help -Loads and validates a FLE type shorthand logfile - -Usage: - FLEcli load [flags] - -Flags: - -h, --help help for load - -i, --input string FLE formatted input file (mandatory) - --interpolate Interpolates the missing time entries. - -Global Flags: - --config string config file (default is $HOME/.FLEcli.yaml) ------ -FLEcli adif --help -Generates an ADIF file based on a FLE type shorthand logfile. - -Usage: - FLEcli adif [flags] - -Flags: - -h, --help help for adif - -i, --input string FLE formatted input file (mandatory) - --interpolate Interpolates the missing time entries. - -o, --output string Output filename - --overwrite Overwrites the output file if it exisits - -s, --sota Generates a SOTA ready ADIF file. - -w, --wwff Generates a WWFF ready ADIF file. - -Global Flags: - --config string config file (default is $HOME/.FLEcli.yaml) ------ -FLEcli csv --help -Generates a SOTA .csv file based on a FLE type shorthand logfile. - -Usage: - FLEcli csv [flags] - -Flags: - -h, --help help for csv - -i, --input string FLE formatted input file (mandatory) - --interpolate Interpolates the missing time entries. - -o, --output string Output filename - --overwrite Overwrites the output file if it exisits - -Global Flags: - --config string config file (default is $HOME/.FLEcli.yaml) -``` +Most comon use cases are described hereafter as examples. ### Example: validate the FLE syntax of a file -To load and validate the FLE formated file (.txt): +To load and validate the FLE formated file (`myActivation.txt`: ``` ./FLEcli load -i=myActivation.txt @@ -141,7 +76,7 @@ As we didn't provide an output filename, the default output, `ON4KJM@ONFF-025920 To generate a CSV file that can be uploaded to https://www.sotadata.org.uk/ to report SOTA activations: ``` -./FLEcli csv -i activation.txt --overwrite --interpolate +./FLEcli csv -i sotaActivation.txt --overwrite --interpolate ``` This command will generate `sotaActivation.csv` based on the `sotaActivation.txt` FLE logfile. If the output file exists, it will be overwritten as the `--overwrite` flag has been specified. diff --git a/doc/install.md b/doc/install.md new file mode 100644 index 0000000..ad92945 --- /dev/null +++ b/doc/install.md @@ -0,0 +1,41 @@ +# Installation + +## Downloading + +The application can be downloaded from the latest release page, found at https://github.com/on4kjm/FLEcli/releases. + +The application is available in the following packaging: +* `FLEcli_v..._macOS_64-bit.tar.gz` is the MacOS version. +* `FLEcli_v..._windows_32-bit.zip` is the Windows version. Only the 32 bit is proposed as it should work also on older Windows version. +* `FLEcli_v..._Linux_64-bit.tar.gz` is the 64 bits distribution for Linux. +* `FLEcli_v..._Linux_32-bit.tar.gz` is the 32 bits distribution for Linux +* `FLEcli_v..._Linux_arm.tar.gz` is the 32 bits ARM (instruction set 6) distribution (for RaspberryPi older models for example) +* `FLEcli_v..._Linux_arm64.tar.gz` is the 64 bits ARM (instruction set 6) distribution + +After downloading the appropriate archive, you can validate its sha256 and compare it with the value in the `checksum.txt` file. + +## Compiling +The application can also be compiled from sources if Golang is available. How to proceed is out of the scope of this notice. + +## Installing + +Unpack it in a convenient location. Depending on your Operating System, you can make it available from any location: +* Adding the directory to the path for Windows +* Creating a (permanent) alias on Linux or MacOS +* Moving the executable to a directory that is in the path, such as `/usr/local/bin` for Linux or MacOs. + +### HomeBrew +Currently there is no Homebrew installation available. + +### Docker +The application is also available as a docker container. +It can be started with: `docker run --rm -i --user $(id -u):$(id -g) -v $(pwd):/FLEcli_data on4kjm/flecli `. If no command is specified, help is displayed. +To avoid typing the whole command, an alias is recomended as described in the [docker specific instructions](../docker/README.md). + +**Important note:** when specifying the path of a file (input or output), it must be relative to the directory the container was started in. + +### MacOS + +**WARNING:** at this stage, the MacOS binary is not signed. It will fail to load on the recent OS version unless a very permissive security setting is enable (which is not advised). + +Please find [here a detailed procedure](install_mac.md) to use FLEcli on a Mac despite the missing signature. \ No newline at end of file diff --git a/doc/install_mac.md b/doc/install_mac.md new file mode 100644 index 0000000..894e1c3 --- /dev/null +++ b/doc/install_mac.md @@ -0,0 +1,26 @@ +# Installation on MacOS + +At this stage, the MacOS FLEcli binary is not signed. It will fail to load on recent MacOS version. + +This procedure will guide you for adding FLEcli to the exception list. + +When the executable has been unpacked in a directory and that you try to execute it in the console (`./FLEcli`), you will get the following error: + +![](pictures/Error_1.png?raw=true) + +Make sure that you choose "cancel" to close the dialog. +Having triggered that error will allow you to enable the exception. + +Enter the "system preference" and choose the "Security Settings". + +![](pictures/System_preference.png?raw=true) + +On the "general" tab, you will see the problem that just occurred ( _"FLEcli" was blocked from use because it is not from an identified developer_ ). Click on the "Allow Anyway" button. + +![](pictures/security_setting.png?raw=true) + +When trying again to execute the application, the error message will be slightly different: + +![](pictures/Error_2.png?raw=true) + +But this time, choose "open". The exception is now registered. \ No newline at end of file diff --git a/doc/pictures/Error_1.png b/doc/pictures/Error_1.png new file mode 100644 index 0000000..a4ef4e8 Binary files /dev/null and b/doc/pictures/Error_1.png differ diff --git a/doc/pictures/Error_2.png b/doc/pictures/Error_2.png new file mode 100644 index 0000000..dd0901f Binary files /dev/null and b/doc/pictures/Error_2.png differ diff --git a/doc/pictures/System_preference.png b/doc/pictures/System_preference.png new file mode 100644 index 0000000..efd641f Binary files /dev/null and b/doc/pictures/System_preference.png differ diff --git a/doc/pictures/security_setting.png b/doc/pictures/security_setting.png new file mode 100644 index 0000000..796c623 Binary files /dev/null and b/doc/pictures/security_setting.png differ diff --git a/doc/usage.md b/doc/usage.md new file mode 100644 index 0000000..81f4f2a --- /dev/null +++ b/doc/usage.md @@ -0,0 +1,96 @@ +# Usage + +## Overview +``` +Usage: + FLEcli [command] + +Available Commands: + adif Generates an ADIF file based on a FLE type shorthand logfile. + csv Generates a SOTA .csv file based on a FLE type shorthand logfile. + help Help about any command + load Loads and validates a FLE type shorthand logfile + version "version" will output the current build information + +Flags: + --config string config file (default is $HOME/.FLEcli.yaml) + -h, --help help for FLEcli + +Use "FLEcli [command] --help" for more information about a command. +``` + + +## "LOAD" command +``` +FLEcli load --help +Loads and validates a FLE type shorthand logfile + +Usage: + FLEcli load [flags] + +Flags: + -h, --help help for load + -i, --input string FLE formatted input file (mandatory) + --interpolate Interpolates the missing time entries. + +Global Flags: + --config string config file (default is $HOME/.FLEcli.yaml) +``` + + +## "ADIF" command +``` +FLEcli adif --help +Generates an ADIF file based on a FLE type shorthand logfile. + +Usage: + FLEcli adif [flags] + +Flags: + -h, --help help for adif + -i, --input string FLE formatted input file (mandatory) + --interpolate Interpolates the missing time entries. + -o, --output string Output filename + --overwrite Overwrites the output file if it exisits + -s, --sota Generates a SOTA ready ADIF file. + -w, --wwff Generates a WWFF ready ADIF file. + +Global Flags: + --config string config file (default is $HOME/.FLEcli.yaml) +``` + +## "CSV" command +``` +FLEcli csv --help +Generates a SOTA .csv file based on a FLE type shorthand logfile. + +Usage: + FLEcli csv [flags] + +Flags: + -h, --help help for csv + -i, --input string FLE formatted input file (mandatory) + --interpolate Interpolates the missing time entries. + -o, --output string Output filename + --overwrite Overwrites the output file if it exisits + +Global Flags: + --config string config file (default is $HOME/.FLEcli.yaml) +``` + +## "VERSION" command +``` +FLEcli version --help +"version" will output the current build information + +Usage: + FLEcli version [flags] + +Flags: + -d, --detailed Prints the detailed version information + -h, --help help for version + +Global Flags: + --config string config file (default is $HOME/.FLEcli.yaml) +``` +The normal output looks like `FLEcli version: v0.0.1`. The detailled output gives additionaly the Git commit hash. the date and time of build and who built the release. \ No newline at end of file diff --git a/docker/Dockerfile b/docker/Dockerfile index 081755f..ebd0740 100644 --- a/docker/Dockerfile +++ b/docker/Dockerfile @@ -1,13 +1,14 @@ FROM alpine:3.12 AS builder -# Copy the executable -COPY FLEcli /FLEcli_bin/FLEcli -RUN chmod +x /FLEcli_bin/FLEcli - +# Copy the executable and make it executable +COPY FLEcli /temp_bin/FLEcli +RUN chmod +x /temp_bin/FLEcli +#we switch to the bare image template as we want the lightest image as possible FROM scratch -COPY --from=builder /FLEcli_bin/FLEcli /FLEcli_bin/FLEcli +#We retrieve the prepared binary and place it in the appropriate location +COPY --from=builder /temp_bin/FLEcli /FLEcli_bin/FLEcli # Create the data directory and set it as the defautl directory WORKDIR /FLEcli_data diff --git a/docker/README.md b/docker/README.md index 8e4c54f..ab8ea15 100644 --- a/docker/README.md +++ b/docker/README.md @@ -1,21 +1,24 @@ -## Building docker image by hand - -* `docker build -t fle_cli .` ## goReleaser built Docker images * `goreleaser --snapshot --skip-publish --rm-dist` -* docker image is named "jmmeessen/flecli". It creates two labels automatically ("latest" and the last release) +* docker image is named "on4kjm/flecli". It creates two labels automatically ("latest" and the last release) + +## Building the image by hand +(this assumes that the Linux executable is available in `dist/`, thus as built by GoReleaser) + +* `docker build -f docker/Dockerfile -t test/test dist/FLEcli_linux_amd64` will create a image called `test/test:latest`. ## Running the container -* `docker run --rm -i fle_cli version -d` -* `docker run --rm -i -v "$(pwd)":/FLEcli_data fle_cli version -d` -* `docker run --rm -i jmmeessen/flecli version -d` +To start and execute the `` use : `docker run --rm -i --user $(id -u):$(id -g) -v $(pwd):/FLEcli_data on4kjm/flecli `. If no command is specified, help is displayed. -* `docker run --rm -i --user $(id -u):$(id -g) -v $(pwd):/FLEcli_data jmmeessen/flecli`. -* `alias FLEcli="docker run --rm --user $(id -u):$(id -g) -v $(pwd):/FLEcli_data jmmeessen/flecli"` +This little command will create an alias that avoids typing the whole command: `alias FLEcli="docker run --rm --user $(id -u):$(id -g) -v $(pwd):/FLEcli_data on4kjm/flecli"`. To use it, type `FLEcli version` for example. + +Important note: when specifying the path of a file (input or output), it must be relative to the directory the container was started in. ## Running bash in the container -* `docker run --rm -i -v "$(pwd)":/FLEcli_data --entrypoint /bin/sh fle_cli` \ No newline at end of file +Note, this doesn't work with the SCRATCH image. You need to use the Alpine base image. Anyway, if you want to enter the container, you know what I am talking about. + +* `docker run --rm -i -v "$(pwd)":/FLEcli_data --entrypoint /bin/sh on4kjm/flecli` \ No newline at end of file