From 76801a41b5f8903192f5081e9ed290fdd9c5742f Mon Sep 17 00:00:00 2001 From: Mark Raynsford Date: Sun, 23 Jun 2024 19:42:36 +0000 Subject: [PATCH] Add README. --- README.in | 95 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 96 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 191 insertions(+) create mode 100644 README.in diff --git a/README.in b/README.in new file mode 100644 index 0000000..ebdde14 --- /dev/null +++ b/README.in @@ -0,0 +1,95 @@ + +## ethermaker + +The `ethermaker` package implements a set of tools and APIs for +generating [MAC addresses](https://en.wikipedia.org/wiki/MAC_address). + +## Features + +* Generates MAC addresses. +* Describes MAC addresses. +* Written in pure Java 21 for safety and portability. +* High coverage test suite (100%, minus an unreachable private constructor). +* [OSGi-ready](https://www.osgi.org/) +* [JPMS-ready](https://en.wikipedia.org/wiki/Java_Platform_Module_System) +* ISC license. + +## Usage + +``` +Usage: ethermaker [options] [command] [command options] + + Options: + --verbose + Set the minimum logging verbosity level. + Default: info + Possible Values: [trace, debug, info, warn, error] + + Use the "help" command to examine specific commands: + + $ ethermaker help help. + + Command-line arguments can be placed one per line into a file, and the file + can be referenced using the @ symbol: + + $ echo help > file.txt + $ echo help >> file.txt + $ ethermaker @file.txt + + Commands: + describe Describe MAC addresses + generate Generate MAC addresses + help Show detailed help messages for commands. + version Show the application version. + + Documentation: + https://www.io7m.com/software/ethermaker/ +``` + +To generate a set of ten random unicast MAC addresses: + +``` +$ ethermaker generate --count 10 +68:cb:e4:d4:2d:94 +22:c5:8c:99:22:15 +8a:2c:2b:cd:71:98 +5e:6e:8b:da:a3:00 +dc:ab:be:0b:5f:14 +d0:24:40:33:53:db +0a:2f:4e:20:eb:11 +8c:95:69:ac:42:d2 +32:9c:da:f3:a6:c8 +f4:de:7f:4d:4e:5b +``` + +To generate a set of ten random MAC addresses under the organization `C419D1`: + +``` +$ ethermaker generate --count 10 --organization C419D1 +c4:19:d1:39:d9:e3 +c4:19:d1:f7:80:95 +c4:19:d1:f8:d0:73 +c4:19:d1:ef:b6:16 +c4:19:d1:1e:60:db +c4:19:d1:25:91:23 +c4:19:d1:7f:59:d1 +c4:19:d1:60:30:0d +c4:19:d1:3e:78:eb +c4:19:d1:a5:f1:cb +``` + +To describe a set of MAC addresses: + +``` +$ ethermaker generate --count 10 --organization C419D1 | ethermaker describe +Address: c4:19:d1:83:97:9b, Multicast: false, Broadcast: false, Local: false +Address: c4:19:d1:8f:84:77, Multicast: false, Broadcast: false, Local: false +Address: c4:19:d1:50:af:bb, Multicast: false, Broadcast: false, Local: false +Address: c4:19:d1:4a:f2:1e, Multicast: false, Broadcast: false, Local: false +Address: c4:19:d1:97:30:58, Multicast: false, Broadcast: false, Local: false +Address: c4:19:d1:d9:d7:a3, Multicast: false, Broadcast: false, Local: false +Address: c4:19:d1:53:d2:98, Multicast: false, Broadcast: false, Local: false +Address: c4:19:d1:ee:f3:d2, Multicast: false, Broadcast: false, Local: false +Address: c4:19:d1:43:c0:41, Multicast: false, Broadcast: false, Local: false +Address: c4:19:d1:e3:53:89, Multicast: false, Broadcast: false, Local: false +``` diff --git a/README.md b/README.md index 21a2bd4..8a98946 100644 --- a/README.md +++ b/README.md @@ -14,3 +14,99 @@ ethermaker | OpenJDK (Temurin) LTS | Linux | [![Build (OpenJDK (Temurin) LTS, Linux)](https://img.shields.io/github/actions/workflow/status/io7m-com/ethermaker/main.linux.temurin.lts.yml)](https://www.github.com/io7m-com/ethermaker/actions?query=workflow%3Amain.linux.temurin.lts)| | OpenJDK (Temurin) Current | Windows | [![Build (OpenJDK (Temurin) Current, Windows)](https://img.shields.io/github/actions/workflow/status/io7m-com/ethermaker/main.windows.temurin.current.yml)](https://www.github.com/io7m-com/ethermaker/actions?query=workflow%3Amain.windows.temurin.current)| | OpenJDK (Temurin) LTS | Windows | [![Build (OpenJDK (Temurin) LTS, Windows)](https://img.shields.io/github/actions/workflow/status/io7m-com/ethermaker/main.windows.temurin.lts.yml)](https://www.github.com/io7m-com/ethermaker/actions?query=workflow%3Amain.windows.temurin.lts)| + +## ethermaker + +The `ethermaker` package implements a set of tools and APIs for +generating [MAC addresses](https://en.wikipedia.org/wiki/MAC_address). + +## Features + +* Generates MAC addresses. +* Describes MAC addresses. +* Written in pure Java 21 for safety and portability. +* High coverage test suite (100%, minus an unreachable private constructor). +* [OSGi-ready](https://www.osgi.org/) +* [JPMS-ready](https://en.wikipedia.org/wiki/Java_Platform_Module_System) +* ISC license. + +## Usage + +``` +Usage: ethermaker [options] [command] [command options] + + Options: + --verbose + Set the minimum logging verbosity level. + Default: info + Possible Values: [trace, debug, info, warn, error] + + Use the "help" command to examine specific commands: + + $ ethermaker help help. + + Command-line arguments can be placed one per line into a file, and the file + can be referenced using the @ symbol: + + $ echo help > file.txt + $ echo help >> file.txt + $ ethermaker @file.txt + + Commands: + describe Describe MAC addresses + generate Generate MAC addresses + help Show detailed help messages for commands. + version Show the application version. + + Documentation: + https://www.io7m.com/software/ethermaker/ +``` + +To generate a set of ten random unicast MAC addresses: + +``` +$ ethermaker generate --count 10 +68:cb:e4:d4:2d:94 +22:c5:8c:99:22:15 +8a:2c:2b:cd:71:98 +5e:6e:8b:da:a3:00 +dc:ab:be:0b:5f:14 +d0:24:40:33:53:db +0a:2f:4e:20:eb:11 +8c:95:69:ac:42:d2 +32:9c:da:f3:a6:c8 +f4:de:7f:4d:4e:5b +``` + +To generate a set of ten random MAC addresses under the organization `C419D1`: + +``` +$ ethermaker generate --count 10 --organization C419D1 +c4:19:d1:39:d9:e3 +c4:19:d1:f7:80:95 +c4:19:d1:f8:d0:73 +c4:19:d1:ef:b6:16 +c4:19:d1:1e:60:db +c4:19:d1:25:91:23 +c4:19:d1:7f:59:d1 +c4:19:d1:60:30:0d +c4:19:d1:3e:78:eb +c4:19:d1:a5:f1:cb +``` + +To describe a set of MAC addresses: + +``` +$ ethermaker generate --count 10 --organization C419D1 | ethermaker describe +Address: c4:19:d1:83:97:9b, Multicast: false, Broadcast: false, Local: false +Address: c4:19:d1:8f:84:77, Multicast: false, Broadcast: false, Local: false +Address: c4:19:d1:50:af:bb, Multicast: false, Broadcast: false, Local: false +Address: c4:19:d1:4a:f2:1e, Multicast: false, Broadcast: false, Local: false +Address: c4:19:d1:97:30:58, Multicast: false, Broadcast: false, Local: false +Address: c4:19:d1:d9:d7:a3, Multicast: false, Broadcast: false, Local: false +Address: c4:19:d1:53:d2:98, Multicast: false, Broadcast: false, Local: false +Address: c4:19:d1:ee:f3:d2, Multicast: false, Broadcast: false, Local: false +Address: c4:19:d1:43:c0:41, Multicast: false, Broadcast: false, Local: false +Address: c4:19:d1:e3:53:89, Multicast: false, Broadcast: false, Local: false +``` +