Documentation improvement

pull/29/head
Jean-Marc MEESSEN 4 years ago committed by GitHub
parent 8afb81eed3
commit 6134577dd0
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

@ -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.

@ -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 <FLEcli command>`. 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.

@ -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.

Binary file not shown.

After

Width:  |  Height:  |  Size: 76 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 112 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 506 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 240 KiB

@ -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.

@ -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

@ -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 `<FLEcli command>` use : `docker run --rm -i --user $(id -u):$(id -g) -v $(pwd):/FLEcli_data on4kjm/flecli <FLEcli command>`. 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`
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`
Loading…
Cancel
Save