diff --git a/CHANGES.md b/CHANGES.md --- a/CHANGES.md +++ b/CHANGES.md @@ -1,7 +1,42 @@ * Hackage: * GitHub: -* Latest Hackage released version: 4.0, 2026-08-24 +* Latest Hackage released version: 4.1, 2026-08-25 + +### Version 4.1, 2026-08-25 + + * Documentation only; no functional changes. + + * Substantially shortened the README. It had grown to fifteen worked examples, + all showing the same output fields with different numbers in them, plus a copy + of the per-platform install commands that already ship inside every release + bundle. The examples are down to four -- an encode with a non-default rounding + mode, a decode, an E8M0 encode, and a two-lane decode -- and the install + section now points at the `README.txt` in the bundle rather than repeating it, + so those steps have a single home and cannot drift. + + * The "Supported formats" section is now just the flag table. The per-format + prose that followed it -- the FP4 (E0M3) and E8M0 explanations, the integer + flavors, the TF32 bit-count note -- is gone; the first three were already + stated in the `--help` output reproduced further down. + + * Downloading a prebuilt binary is now the first thing the README talks about, + under its own heading, instead of being a sub-section whose point was hidden in + a parenthetical. Building from Hackage is presented as the alternative, and + each platform bullet links to the latest release. + + * Replaced the README's markdown tables with lists. Hackage renders the README + outside the `#description` pane, and its stylesheet only borders tables inside + that pane, so a table there comes out unstyled and the columns run together. + + * Dropped the per-platform GUI build instructions from the README; each GUI's + own directory documents itself. `GUI/winGUI/README.md` is new; `GUI/swiftGUI/` + and `GUI/tclGUI/` already had one. The note about needing `wish` on Linux went + with it -- when `wish` is missing, the binary already prints the `apt`/`dnf`/`nix` + command to install it. + + * Reworded the cabal Description's pointer to the releases page: it now leads + with not needing a Haskell toolchain, rather than with the word "releases". ### Version 4.0, 2026-08-24 diff --git a/README.md b/README.md --- a/README.md +++ b/README.md @@ -1,7 +1,5 @@ ## Decode/Encode Integers, Words, and IEEE754 and other float formats -On Hackage: http://hackage.haskell.org/package/crackNum - `crackNum` shows you exactly how a number is laid out in memory: the bit pattern, its fields, the classification, and the value in binary, octal, decimal, and hex. It works in both directions: @@ -11,79 +9,39 @@ - **Decoding**: give it a bit-pattern (`0xdeadbeef`, `0b0110`, `32'hfdc71fc6`), and it shows the value it stands for. -### Installation - -#### Prebuilt binaries (nothing to build, no Haskell toolchain) - -The easiest way to get crackNum is from the -[Releases page](https://github.com/LeventErkok/crackNum/releases). Each bundle is -self-contained: the `crackNum` executable, a copy of `z3`, the graphical interface, -a LICENSE, and a README repeating the steps below. - -| Platform | Asset | Notes | -| --- | --- | --- | -| Linux (x86_64) | `crackNum--linux-x86_64.tar.gz` | Statically linked, so there is no glibc or distribution requirement: it runs as-is on any x86_64 Linux, old or new. | -| macOS (Apple Silicon) | `crackNum--macos-arm64.tar.gz` | Includes `CrackNum.app`. Ad-hoc signed rather than notarized, so clear the quarantine flag as shown below. | -| Windows (x86_64) | `crackNum--windows-x86_64.zip` | Includes `CrackNumGUI.exe`. Unsigned, so SmartScreen warns on first run; see below. | - -Unpack the bundle anywhere you like, then put the files somewhere on your `PATH`. -`z3` has to go there too, since crackNum shells out to it for every operation. - -**Linux** — all three files, the GUI script included: - -``` -$ tar xzf crackNum--linux-x86_64.tar.gz -$ cd crackNum--linux-x86_64 -$ mkdir -p ~/bin && cp crackNum z3 crackNum.tcl ~/bin/ -$ export PATH=$HOME/bin:$PATH # put this in your shell's startup file -``` - -The GUI is a Tcl/Tk script, so unlike the two binaries it needs something from your -system: `wish` on your `PATH`. Install it with `sudo apt install tk` (Debian/Ubuntu), -`sudo dnf install tk` (RHEL/Fedora), or `nix profile install nixpkgs#tk`. - -**macOS** — clear the quarantine flag first, since these are ad-hoc signed rather -than notarized and nothing will run before you do: - -``` -$ tar xzf crackNum--macos-arm64.tar.gz -$ cd crackNum--macos-arm64 -$ xattr -dr com.apple.quarantine crackNum z3 CrackNum.app -$ mkdir -p ~/bin && cp crackNum z3 ~/bin/ -$ cp -R CrackNum.app /Applications/ -$ export PATH=$HOME/bin:$PATH # put this in your login shell's startup file -``` +### Download crackNum -**Windows** — keep the files together in one folder; `crackNum.exe` looks beside -itself for the GUI and the solver before consulting your `PATH`: +**→ [Ready-to-run bundles for Linux, macOS, and Windows](https://github.com/LeventErkok/crackNum/releases)** -``` -> Expand-Archive crackNum--windows-x86_64.zip -DestinationPath . -> cd crackNum--windows-x86_64 -> New-Item -ItemType Directory -Force $env:USERPROFILE\bin -> Copy-Item * $env:USERPROFILE\bin -``` +Nothing to build, no Haskell toolchain. Each bundle carries the `crackNum` +executable, a copy of `z3`, the GUI, a LICENSE, and a `README.txt` with the +install steps for that platform. -Then add that folder to your `PATH` and open a new terminal, since a `PATH` change -does not reach terminals that are already running. The binaries are not code-signed, -so the first run may raise a SmartScreen prompt; choose "More info" then "Run -anyway", or tick "Unblock" in the .zip's Properties before extracting. + - **Linux (x86_64)** — [`crackNum--linux-x86_64.tar.gz`](https://github.com/LeventErkok/crackNum/releases/latest). + Statically linked, so it runs as-is on any x86_64 Linux, old or new. + - **macOS (Apple Silicon)** — [`crackNum--macos-arm64.tar.gz`](https://github.com/LeventErkok/crackNum/releases/latest). + Includes `CrackNum.app`. Ad-hoc signed, so clear the quarantine flag first. + - **Windows (x86_64)** — [`crackNum--windows-x86_64.zip`](https://github.com/LeventErkok/crackNum/releases/latest). + Includes `CrackNumGUI.exe`. Unsigned, so SmartScreen warns on first run. -Any of the three, check with: +Unpack it, put the files on your `PATH` — `z3` included, since crackNum shells +out to it for every operation — and check with: ``` $ crackNum -fsp 3.5 $ crackNum --gui ``` -#### From Hackage +### Building from source +crackNum is on [Hackage](http://hackage.haskell.org/package/crackNum): + ``` $ cabal install crackNum ``` -Installed this way you also need [z3](https://github.com/Z3Prover/z3) on your -`PATH`: crackNum delegates the floating-point reasoning to it, via +This way you also need [z3](https://github.com/Z3Prover/z3) on your `PATH`: +crackNum delegates the floating-point reasoning to it, via [SBV](http://hackage.haskell.org/package/sbv). ### Supported formats @@ -107,51 +65,11 @@ Significand sizes include the implicit bit. -FP4 (E0M3) is the odd one out: with no exponent bits at all it is really a 4-bit -sign-magnitude *integer*, holding a sign and a 3-bit magnitude. It covers -7 to 7, -with both a positive and a negative zero, and has neither NaN nor Inf. - -E8M0 is the odd one out in the other direction: it is the shared scale of the OCP -Microscaling (MX) formats, and is *all* exponent. With no sign bit and no -significand, every value it holds is a power of two, from 2^-127 to 2^127. It has -no zero and no subnormals -- an all-zero encoding means 2^-127, not zero -- and no -infinities; `0xFF` is its one and only NaN. Negative inputs are rejected, and -values outside its range saturate to the nearest end-point. - -Integers come in two flavors: `-iN` for a signed `N`-bit 2's complement integer, -and `-wN` for an unsigned `N`-bit word. Both `N` and the arbitrary float sizes -can be as large as you like, within machine-word limits. - -Note that TF32 is cracked as its 19 architectural bits; hardware typically -carries these in a 32-bit container with the remaining bits unused. - Rounding mode is selected with `-r`, and defaults to `RNE` if not given: `RNE` (nearest, ties to even), `RNA` (nearest, ties away), `RTP` (towards positive infinity), `RTN` (towards negative infinity), and `RTZ` (towards zero). -### Example: Encode a decimal number as a single-precision IEEE754 number -``` -$ crackNum -fsp -- -2.3e6 -Satisfiable. Model: - ENCODED = -2300000.0 :: Float - 3 2 1 0 - 1 09876543 21098765432109876543210 - S ---E8--- ----------S23---------- - Binary layout: 1 10010100 00011000110000110000000 - Hex layout: CA0C 6180 - Precision: Single - Sign: Negative - Exponent: 21 (Stored: 148, Bias: 127) - Classification: FP_NORMAL - Binary: -0b1.0001100011000011p+21 - Octal: -0o1.061414p+21 - Decimal: -2300000.0 - Hex: -0x2.3186p+20 - Rounding mode: RNE: Round nearest ties to even. - Note: Conversion from "-2.3e6" was exact. No rounding happened. -``` - -### Example: Encode with a different rounding mode +### Example: Encode a single-precision float, rounding towards zero ``` $ crackNum -fsp 1.3 -rRTZ Satisfiable. Model: @@ -173,7 +91,7 @@ Note: Conversion from "1.3" was not faithful. Status: Inexact. ``` -### Example: Decode a single-precision IEEE754 number float from memory-layout +### Example: Decode a single-precision bit-pattern ``` $ crackNum -fsp 0xfc00 abc1 Satisfiable. Model: @@ -193,99 +111,6 @@ Hex: -0x2.02af04p+120 ``` -### Example: Encode as an E4M3 FP8 float -``` -$ crackNum -fe4m3 2.5 -Satisfiable. Model: - ENCODED = 2.5 :: E4M3 - 7 6543 210 - S -E4- S3- - Binary layout: 0 1000 010 - Hex layout: 42 - Precision: 4 exponent bits, 3 significand bits - Sign: Positive - Exponent: 1 (Stored: 8, Bias: 7) - Classification: FP_NORMAL - Binary: 0b1.01p1 - Octal: 0o2.4 - Decimal: 2.5 - Hex: 0x2.8 -``` - -### Example: Decode an FP4 (E2M1) float -``` -$ crackNum -ffp4 0b0111 -Satisfiable. Model: - DECODED = 6.0 :: FP4 - 3 21 0 - S E2 S - Binary layout: 0 11 1 - Hex layout: 7 - Precision: 2 exponent bits, 1 significand bit - Sign: Positive - Exponent: 2 (Stored: 3, Bias: 1) - Classification: FP_NORMAL - Binary: 0b1.1p+2 - Octal: 0o6 - Decimal: 6.0 - Hex: 0x6 -``` - -### Example: Decode an FP4 (E0M3) sign-magnitude integer -``` -$ crackNum -ffp4e0m3 0b1101 -Satisfiable. Model: - DECODED = -5 :: FP4E0M3 - 3 210 - S -M- - Binary layout: 1 101 - Hex layout: D - Type: 4-bit sign-magnitude integer - Sign: Negative - Binary: -0b101 - Octal: -0o5 - Decimal: -5 - Hex: -0x5 -``` - -### Example: Encode an FP4 (E0M3) sign-magnitude integer -``` -$ crackNum -ffp4e0m3 -- -5 -Satisfiable. Model: - ENCODED = -5 :: FP4E0M3 - 3 210 - S -M- - Binary layout: 1 101 - Hex layout: D - Type: 4-bit sign-magnitude integer - Sign: Negative - Binary: -0b101 - Octal: -0o5 - Decimal: -5 - Hex: -0x5 - Rounding mode: RNE: Round nearest ties to even. - Note: Conversion from "-5" was exact. No rounding happened. -``` - -### Example: Decode an E8M0 MX scale -``` -$ crackNum -fe8m0 0xFE -Satisfiable. Model: - DECODED = 1.7014118346046923e38 :: E8M0 - 76543210 - ---E8--- - Binary layout: 11111110 - Hex layout: FE - Precision: 8 exponent bits, no significand - Sign: Positive (always) - Exponent: 127 (Stored: 254, Bias: 127) - Classification: FP_NORMAL - Binary: 0b1p+127 - Octal: 0o2p+126 - Decimal: 1.7014118346046923e38 - Hex: 0x8p+124 -``` - ### Example: Encode an E8M0 MX scale Only powers of two are representable, so everything else rounds according to `-r`: ``` @@ -308,79 +133,7 @@ Note: Original value of 10.0 was rounded to 8.0. ``` -### Example: Encode a TensorFloat-32 number -``` -$ crackNum -ftf32 2.5 -Satisfiable. Model: - ENCODED = 2.5 :: FloatingPoint 8 11 - 1 0 - 8 76543210 9876543210 - S ---E8--- ---S10---- - Binary layout: 0 10000000 0100000000 - Hex layout: 2 0100 - Precision: 8 exponent bits, 10 significand bits - Sign: Positive - Exponent: 1 (Stored: 128, Bias: 127) - Classification: FP_NORMAL - Binary: 0b1.01p1 - Octal: 0o2.4 - Decimal: 2.5 - Hex: 0x2.8 - Rounding mode: RNE: Round nearest ties to even. - Note: Conversion from "2.5" was exact. No rounding happened. -``` - -### Example: Decode a custom (2+3) float from memory-layout -``` -$ crackNum -f2+3 0b10011 -Satisfiable. Model: - DECODED = -0.75 :: FloatingPoint 2 3 - 4 32 10 - S E2 S2 - Binary layout: 1 00 11 - Hex layout: 13 - Precision: 2 exponent bits, 2 significand bits - Sign: Negative - Exponent: 0 (Subnormal, with fixed exponent value. Stored: 0, Bias: 1) - Classification: FP_SUBNORMAL - Binary: -0b1.1p-1 - Octal: -0o6p-3 - Decimal: -0.75 - Hex: -0xcp-4 -``` - -### Example: Encode an integer as a 7-bit signed word -``` -$ crackNum -i7 12 -Satisfiable. Model: - ENCODED = 12 :: IntN 7 - 654 3210 - Binary layout: 000 1100 - Hex layout: 0C - Type: Signed 7-bit 2's complement integer - Sign: Positive - Binary: 0b1100 - Octal: 0o14 - Decimal: 12 - Hex: 0xc -``` - -### Example: Decode a 4-bit unsigned word -``` -$ crackNum -w4 0xE -Satisfiable. Model: - DECODED = 14 :: WordN 4 - 3210 - Binary layout: 1110 - Hex layout: E - Type: Unsigned 4-bit word - Binary: 0b1110 - Octal: 0o16 - Decimal: 14 - Hex: 0xe -``` - -### Example: Decode two half-precision floats in two lanes +### Example: Decode two half-precision lanes ``` $ crackNum -l2 -fhp 32\'hfdc71fc6 == Lane 1 ============================================================ @@ -415,60 +168,17 @@ Hex: 0x1.f18p-8 ``` -If you use the verilog notation (`N'h...`), the number of lanes is inferred from -the width, so `-l` is optional in that case. - -### Graphical interface (optional) - -Optionally, crackNum comes with a GUI: pick a format on the left, type a value, -and see the encoding/decoding in detail. It is entirely optional — crackNum is -fully functional as a command-line tool without it. The GUI is just a thin -front-end that calls the `crackNum` binary underneath, so it supports exactly -the same formats. - -If you installed from a [release bundle](#prebuilt-binaries-nothing-to-build-no-haskell-toolchain) -the GUI is already in it, and there is nothing to build on any of the three. The rest -of this section is for installing from Hackage or from a source checkout. - -**macOS** — a native Swift/AppKit app (`GUI/swiftGUI/`). It is not part of the -Hackage package, so building it yourself needs a clone of the repository and the -Swift compiler that comes with the Xcode Command Line Tools -(`xcode-select --install`): - -``` -$ git clone https://github.com/LeventErkok/crackNum.git -$ cd crackNum/GUI/swiftGUI -$ make install # builds CrackNum.app and copies it into /Applications -``` - -**Linux** — a Tcl/Tk script (`GUI/tclGUI/crackNum.tcl`). The script ships with the -package and is installed alongside the binary, so there is nothing to build; you -only need `wish` (Tk 8.6+): - -``` -$ nix profile install nixpkgs#tk # or: sudo apt install tk / sudo dnf install tk -``` - -Then `crackNum --gui` just works. If you want to run a modified copy of the -script, either put it on your PATH as `crackNum.tcl`, or point at it directly -with `CRACKNUM_TCL=/path/to/crackNum.tcl`. +With verilog notation (`N'h...`) the lane count is inferred from the width, so +`-l` is optional. -**Windows** — a native WinForms app (`GUI/winGUI/`). It targets .NET Framework 4.8, -which ships as part of Windows 10 and 11, so the built executable needs no runtime -install. Like the macOS app it is not part of the Hackage package; building it -needs a clone and the .NET SDK: +### Graphical interface -``` -> git clone https://github.com/LeventErkok/crackNum.git -> cd crackNum\GUI\winGUI -> dotnet build -c Release -``` +An optional GUI: pick a format on the left, type a value, see the result. It is a +thin front-end over the `crackNum` binary, so it supports exactly the same formats. -Put the resulting `CrackNumGUI.exe` next to `crackNum.exe`, or point at it with -`CRACKNUM_GUI=C:\path\to\CrackNumGUI.exe`. +![The crackNum GUI](https://raw.githubusercontent.com/LeventErkok/crackNum/master/crackNumGUI.png) -On all three platforms, launch the GUI from the command line via the `--gui` option, -which forwards any format/rounding flags and value to the app: +Launch it with `--gui`, which forwards any flags and value to the app: ``` $ crackNum --gui -- open the graphical interface @@ -476,9 +186,6 @@ $ crackNum --gui 0xdeadbeef -- open it pre-filled with a value to decode ``` -Bad flags are diagnosed before the GUI comes up: `crackNum -ft32 4 --gui` -reports the unknown format instead of opening an empty window. - ### Usage info ``` Usage: crackNum value OR binary/hex-pattern @@ -565,6 +272,5 @@ - If you use verilog input format, then we will infer the number of lanes unless you provide it. ``` -VIM users: You can use the http://github.com/LeventErkok/crackNum/blob/master/crackNum.vim file to -use CrackNum directly from VIM. Simply locate your cursor on the text to crack, and use the -command `:CrackNum options`. +VIM users: [crackNum.vim](http://github.com/LeventErkok/crackNum/blob/master/crackNum.vim) +cracks the text under the cursor with `:CrackNum options`. diff --git a/crackNum.cabal b/crackNum.cabal --- a/crackNum.cabal +++ b/crackNum.cabal @@ -1,15 +1,15 @@ Cabal-version : 2.2 Name : crackNum -Version : 4.0 +Version : 4.1 Synopsis : Crack various integer and floating-point data formats Description : Crack IEEE-754 and other float formats and arbitrary sized words and integers, showing the layout. Along with a command-line interface on any platform, native MacOS and Windows GUIs and a Tcl-based Linux GUI are available as well: . <> . - For details, please see: . See the - - for binary releases for Mac, Linux, and Windows. + For details, please see: . + . + You do not need a Haskell toolchain to use crackNum: the has ready-to-run bundles for Mac, Linux, and Windows. License : BSD-3-Clause License-file : LICENSE Author : Levent Erkok