Doc option --pack new usage

Author: jondy

docs/reference/man.rst

@@ -149,7 +149,7 @@ Generate obfuscated scripts and all the required runtime files.
 --assert-import                 assert module is obfuscated :option:`... <--assert-import>`
 --assert-call                   assert function is obfuscated  :option:`... <--assert-call>`
 
---pack BUNDLE                   repack bundle with obfuscated scripts  :option:`... <--pack>`
+--pack <onefile|onedir>         Obfuscate scripts then pack :option:`... <--pack>`
 
 --use-runtime PATH              use shared runtime package :option:`... <--use-runtime>`
 
@@ -562,19 +562,33 @@ The function :func:`__assert_armored__` is a builtin function in obfuscated scri
 
 This option neither touches statement ``from import``, nor the module imported by function ``__import__``.
 
-.. option:: --pack BUNDLE
+.. option:: --pack <onefile,onedir>
 
-            Repack bundle with obfuscated scripts
+            Obfuscate script first, then pack the obfuscated scripts to bundle
 
-Here ``BUNDLE`` is an executable file generated by PyInstaller_
+.. versionchanged:: 8.5.4
 
-Pyarmor just obfuscates the script first.
+   Before v8.5.4, user need first generate an executable file by PyInstaller_
 
-Then unpack the bundle.
+   Now everything is done by Pyarmor
 
-Next replace all the ``.pyc`` in the bundle with obfuscated scripts, and append all the :term:`runtime files` to the bundle.
+   The old method still works, but it's deprecated.
 
-Finally repack the bundle and overwrite the original ``BUNDLE``.
+Once this option is used, pyarmor will analysis the source of main script, and find all the imported modules and packages which are in the same path of main script. All of these used modules and packages will be obfuscated automatically
+
+Then pyarmor will call PyInstaller_ to pack the obfuscated scripts to one file or one folder bundle.
+
+For example, generate one file bundle::
+
+  pyarmor gen --pack onefile foo.py
+
+  ls dist/
+
+Sometimes it need specify option :option:`-r` to make sure all the child packages are obfuscated. For example::
+
+  pyarmor gen --pack onefolder -r foo.py
+
+.. seealso:: :doc:`../topic/repack`
 
 .. option:: --use-runtime PATH
 
@@ -759,7 +773,7 @@ Set option to boolean value::
     $ pyarmor cfg wrap_mode 0
     $ pyarmor cfg wrap_mode=1
 
-Set option to string value::
+Set option to string value, it must leave blank around ``=``::
 
     $ pyarmor cfg outer_keyname "sky.lic"
     $ pyarmor cfg outer_keyname = "sky.lic"

docs/topic/repack.rst

@@ -6,29 +6,86 @@ Insight Into Pack Command
 
 .. program:: pyarmor gen
 
-Pyarmor 8.0 has no command pack, but option :option:`--pack`. It could specify an executable file generated by PyInstaller_::
+Pyarmor 8.0 has no command pack, but option :option:`--pack`, once it's set, pyarmor will automatically pack the scripts into one bundle.
 
-  pyinstaller foo.py
-  pyarmor gen --pack dist/foo/foo foo.py
+Packing Scripts Automatically
+=============================
 
-If this option isn't set, pyarmor only obfuscates the scripts.
+.. versionadded:: 8.5.4
 
-If this option is set, pyarmor first obfuscates the scripts, then does extra work:
+It accept 2 values: ``onefile`` and ``onedir``, just as PyInstaller_
 
-* Unpacking this executable to a temporary folder
-* Replacing the scripts in bundle with obfuscated ones
-* Appending runtime files to the bundle in this temporary folder
-* Repacking this temporary folder to an executable file and overwrite the old
+Actually Pyarmor need call PyInstaller_ to generate final bundle, so first install PyInstaller_::
 
-In Darwin, let obfuscated scripts work in both intel and Apple Silicon by extra option ``--platform darwin.x86_64,darwin.arm64``::
+  pip install pyinstaller
 
-  pyarmor gen --pack dist/foo/foo --platform darwin.x86_64,darwin.arm64 foo.py
+Suppose our project tree like this::
 
-.. important::
+    project/
+        ├── foo.py
+        ├── queens.py
+        └── joker/
+            ├── __init__.py
+            ├── queens.py
+            └── config.json
 
-   Only listed scripts are obfuscated, if need obfuscate more scripts and sub packages, list all of them in command line. For example::
+Let's check what happens when the following commands are executed::
 
-     pyarmor gen --pack dist/foo/foo -r *.py dir1 dir2 ...
+  cd project
+  pyarmor gen --pack onefile foo.py
+
+1. Pyarmor first open `foo.py`, then find it need `queens.py` and package `joker`
+2. Then obfuscate all of them to one temporary path `.pyarmor/pack/dist`
+3. Next pyarmor call PyInstaller with plain script `foo.py`, to get all the system packages used by `foo.py`, and save all of them to hiddenimports table.
+4. Finally pyarmor call PyInstaller again but with obfuscated scripts and all of hidden imports to generate final bundle.
+
+Now let's run the final bundle, it's `dist/foo` or `dist/foo.exe`::
+
+  ls dist/foo
+  dist/foo
+
+If need one folder bundle, just pass `onedir` to pack::
+
+  pyarmor gen --pack onedir foo.py
+  ls dist/foo
+  dist/foo/foo
+
+Checking Obfuscated Scripts Have Been Packed
+--------------------------------------------
+
+Add one line in the script ``foo.py`` or ``joker/__init__.py``
+
+.. code-block:: python
+
+    print('this is __pyarmor__', __pyarmor__)
+
+If it's not obfuscated, the final bundle will raise error. Because builtin name ``__pyarmor__`` is only available in the obfuscated scripts.
+
+Using More PyInstaller Options
+------------------------------
+
+If need extra PyInstaller options, using configuration item ``pack:pyi_options``. For example, reset it with one PyInstaller option ``-w``::
+
+  pyarmor cfg pack:pyi_options = "-w"
+
+Let's append another option ``-i``, note that it must be one whitespace between option ``-i`` and its value, do not use ``=``. For example::
+
+  pyarmor cfg pack:pyi_options ^ "-i favion.ico"
+
+Append another option::
+
+  pyarmor cfg pack:pyi_options ^ "--add-data joker/config.json:joker"
+
+.. seealso:: :ref:`pyarmor cfg`
+
+Using More Obfuscation Options
+------------------------------
+
+In Darwin, let obfuscated scripts work in both intel and Apple Silicon by extra option ``--platform darwin.x86_64,darwin.arm64``::
+
+  pyarmor gen --pack onefile --platform darwin.x86_64,darwin.arm64 foo.py
+
+You can use any other obfuscation options to improve security, but some of them may not work. For example, :option:`--restrict` can't be used with :option:`--pack`.
 
 Packing obfuscated scripts manually
 ===================================
@@ -134,6 +191,31 @@ If it's not obfuscated, the final bundle will raise error.
 .. [#] Just let PyInstaller could find runtime package without extra pypath
 .. [#] Most of the other PyInstaller options could be used here
 
+Packing with PyInstaller Bundle
+===============================
+
+.. deprecated:: 8.5.4
+
+    Use :option:`--pack` ``onefile`` or ``onedir`` instead.
+
+The option :option:`--pack` also could accept an executable file generated by PyInstaller_::
+
+  pyinstaller foo.py
+  pyarmor gen --pack dist/foo/foo foo.py
+
+But only PyInstaller < 6.0 works by this method. If this option is set, pyarmor first obfuscates the scripts, then:
+
+* Unpacking this executable to a temporary folder
+* Replacing the scripts in bundle with obfuscated ones
+* Appending runtime files to the bundle in this temporary folder
+* Repacking this temporary folder to an executable file and overwrite the old
+
+.. important::
+
+   Only listed scripts are obfuscated, if need obfuscate more scripts and sub packages, list all of them in command line. For example::
+
+     pyarmor gen --pack dist/foo/foo -r *.py dir1 dir2 ...
+
 Segment fault in Apple M1
 =========================
 

docs/tutorial/obfuscation.rst

@@ -286,41 +286,45 @@ And then obfuscate the scripts again.
 Packing obfuscated scripts
 ==========================
 
-Pyarmor need PyInstaller to pack scripts first, then replace plain scripts with obfuscated ones in bundle.
+Pyarmor need PyInstaller to pack the obfuscated scripts, so first make sure PyInstaller has been installed. If not, simple install it by this command::
+
+  pip install pyinstaller
 
 Packing to one file
 -------------------
 
-First packing script to one file by PyInstaller with option ``-F``::
+.. versionchanged:: 8.5.4
+
+   Before v8.5.4, it need more work, please check old version documentation (v8.5.3).
 
-    $ pyinstaller -F foo.py
+Packing script to one file only need one command::
 
-It generates one bundle file ``dist/foo``, pass this to pyarmor::
+  pyarmor gen --pack onefile foo.py
 
-    $ pyarmor gen -O obfdist --pack dist/foo foo.py
+Run the final bundle::
 
-This command will obfuscate ``foo.py`` first, then repack ``dist/foo``, replace the original ``foo.py`` with ``obfdist/foo.py``, and append all the runtime files to bundle.
+  dist/foo
 
-The final output is still ``dist/foo``::
+Pyarmor will automatically obfuscate `foo.py` and all the other used modules and packages in the same path, then pack the obfuscated to one bundle.
 
-    $ dist/foo
+.. important::
+
+   Please pass plain script in command line, for example, `foo.py` should not been obfuscated.
 
 Packing to one folder
 ---------------------
 
-First packing script to one folder by PyInstaller::
-
-    $ pyinstaller foo.py
+.. versionchanged:: 8.5.4
 
-It generates one bundle folder ``dist/foo``, and an executable file ``dist/foo/foo``, pass this executable to pyarmor::
+   Before v8.5.4, it need more work, please check old version documentation (v8.5.3).
 
-    $ pyarmor gen -O obfdist --pack dist/foo/foo foo.py
+Packing script to one folder::
 
-Like above section, ``dist/foo/foo`` will be repacked with obfuscated scripts.
+  pyarmor gen --pack onefolder foo.py
 
-Now run it::
+Run the final bundle::
 
-    $ dist/foo/foo
+  dist/foo/foo
 
 More information about pack feature, refer to :doc:`../topic/repack`
 

src/cli/repack.py

@@ -6,7 +6,6 @@
 import sys
 import tempfile
 
-from json import load as json_load
 from importlib._bootstrap_external import _code_to_timestamp_pyc
 from subprocess import check_call, check_output, DEVNULL