Merge pull request #498 from kissgyorgy/pypi-release

Pypi release

Author: martonilles

.github/actions/setup-dependencies/action.yml

@@ -2,7 +2,8 @@ inputs:
   python-version:
     description: "Python version to setup"
     required: false
-    default: 3.8
+    default: "3.8"
+
 runs:
   using: "composite"
   steps:

.github/workflows/release.yml

@@ -0,0 +1,20 @@
+name: PyPI Release
+
+on:
+  release:
+    types: [created]
+
+jobs:
+  release:
+    runs-on: ubuntu-20.04
+
+    steps:
+      - name: Checkout source code
+        uses: actions/checkout@v2
+
+      - name: Setup dependencies
+        uses: ./.github/actions/setup-dependencies
+
+      - run: poetry publish --build
+        env:
+          POETRY_PYPI_TOKEN_PYPI: ${{secrets.POETRY_PYPI_TOKEN_PYPI}}

.github/workflows/main.yml .github/workflows/run-tests.yml.github/workflows/main.yml renamed to .github/workflows/run-tests.yml

@@ -1,4 +1,4 @@
-name: Main
+name: Run checks and tests
 
 on:
   push:

docs/installation.md

@@ -5,6 +5,37 @@ hide:
 
 # Installation
 
+Unblob consists of two main parts:
+
+- unblob, the Python package (with optional Rust modules).
+- extractor command line tools like `7zip`, `unar`, etc. (See [Extractors](./extractors.md) for explanation.)
+
+All of these need to be installed to make unblob fully functional.  
+Depending the packaging solution you choose, you might need to
+install external extractors manually.
+
+## Python package
+
+unblob can be installed (without the extractors) from PyPI (Python Package Index).  
+This might be the easiest method, depending on whether you have Python 3 installed already.
+
+1.  First, install the Python package:
+
+        python3 -m pip install --user unblob
+
+    This will install the `unblob` script in `~/.local/bin`. You can put that
+    directory in your `PATH` environment variable, or call it directly.
+
+    !!! Warning
+
+        System-wide installation (with `sudo`) is not recommended, because it can potentially break your system.
+
+2.  Make sure to [install extractors](#install-extractors).
+
+3.  Check that everything works correctly:
+
+        unblob --show-external-dependencies
+
 ## Docker image
 
 unblob can be used right away from a `docker` image: `ghcr.io/onekey-sec/unblob:latest`,
@@ -35,34 +66,33 @@ docker run --rm --pull always ghcr.io/onekey-sec/unblob:latest --help
 unblob can be built and run using the [Nix](https://nixos.org) package manager.
 The Nix derivation installs all 3rd party dependencies.
 
-1. [Install and configure Nix](https://nixos.org/download.html).
+1.  [Install and configure Nix](https://nixos.org/download.html).
 
-1. _Optional_: enable the experimental features so that you don't need to pass  
-  `--extra-experimental-features "nix-command flakes"` to `nix` command invocations:
+1.  _Optional_: enable the experimental features so that you don't need to pass  
+    `--extra-experimental-features "nix-command flakes"` to `nix` command invocations:
 
-        cat > ~/.config/nix/nix.conf <<EOF
-        experimental-features = nix-command flakes
-        EOF
+          cat > ~/.config/nix/nix.conf <<EOF
+          experimental-features = nix-command flakes
+          EOF
 
-1. _Optional_: use pre-built binaries from GitHub using [cachix](https://app.cachix.org/cache/unblob):
+1.  _Optional_: use pre-built binaries from GitHub using [cachix](https://app.cachix.org/cache/unblob):
 
         nix-env -iA cachix -f https://cachix.org/api/v1/install
         cachix use unblob
 
-1. Install unblob:
+1.  Install unblob:
 
         nix profile install github:onekey-sec/unblob
 
 - Check that everything works correctly:
 
         unblob --show-external-dependencies
 
-
 ## From source
 
-1. Install [Git](https://git-scm.com/download/) if you don't have it yet.
-2. Install the [Poetry](https://python-poetry.org/docs/#installation) Python package manager.
-3. **Clone** the unblob **repository from GitHub**:
+1.  Install [Git](https://git-scm.com/download/) if you don't have it yet.
+2.  Install the [Poetry](https://python-poetry.org/docs/#installation) Python package manager.
+3.  **Clone** the unblob **repository from GitHub**:
 
         git clone https://github.com/onekey-sec/unblob.git
 
@@ -74,56 +104,26 @@ The Nix derivation installs all 3rd party dependencies.
             cd unblob
             UNBLOB_BUILD_RUST_EXTENSION=1 poetry install --no-dev
 
-    2. Python packages only:
+    2.  Python packages only:
 
             cd unblob
             poetry install --no-dev
 
-5. Install **required extractors** with your operating system package manager:
-
-    - on Ubuntu 22.04, install extractors with APT:
-
-            sudo apt install e2fsprogs p7zip-full unar zlib1g-dev liblzo2-dev lzop lziprecover img2simg libhyperscan-dev zstd
-
-    - If you need squashfs support, install sasquatch:
+    3.  Make sure you [installed all extractors](#install-extractors).
 
-            curl -L -o sasquatch_1.0_amd64.deb https://github.com/onekey-sec/sasquatch/releases/download/sasquatch-v1.0/sasquatch_1.0_amd64.deb
-            sudo dpkg -i sasquatch_1.0_amd64.deb
-            rm sasquatch_1.0_amd64.deb
-
-6. Check that everything works correctly:
-
-        unblob --show-external-dependencies
-
-    - Dependencies are all in place:
-```console
-$ poetry run unblob --show-external-dependencies
-The following executables found installed, which are needed by unblob:
-    7z                          ✓
-    debugfs                     ✓
-    jefferson                   ✓
-    lz4                         ✓
-    lziprecover                 ✓
-    lzop                        ✓
-    sasquatch                   ✓
-    sasquatch-v4be              ✓
-    simg2img                    ✓
-    ubireader_extract_files     ✓
-    ubireader_extract_images    ✓
-    unar                        ✓
-    yaffshiv                    ✓
-    zstd                        ✓
-```
+    4.  Check that everything works correctly:
 
-7. (Optional) Install it system wide.
+            poetry run unblob --show-external-dependencies
 
-You can install unblob system wide in two operations:
+## Install extractors
 
-    1. Build the unblob distribution package:
+1.  With your operating system package manager:  
+    On Ubuntu 22.04, install extractors with APT:
 
-        cd unblob
-        poetry build
+        sudo apt install e2fsprogs p7zip-full unar zlib1g-dev liblzo2-dev lzop lziprecover img2simg libhyperscan-dev zstd
 
-    2. Install the unblob distribution package:
+2.  If you need **squashfs support**, install sasquatch:
 
-        sudo python3 -m pip install dist/unblob-<version>.tar.gz
+        curl -L -o sasquatch_1.0_amd64.deb https://github.com/onekey-sec/sasquatch/releases/download/sasquatch-v1.0/sasquatch_1.0_amd64.deb
+        sudo dpkg -i sasquatch_1.0_amd64.deb
+        rm sasquatch_1.0_amd64.deb