bl_pkg/readme.rst

   1
   2 ##################
   3 Blender Extensions
   4 ##################
   5
   6 Directory Layout
   7 ================
   8
   9 ``./blender_addon/bl_pkg/cli/``
  10    The stand-alone command line utility to manage extensions.
  11
  12 ``./blender_addon/bl_pkg/``
  13    The Blender add-on which wraps the command line utility
  14    (abstracts details of interacting with the package manager & repositories).
  15
  16 ``./tests/``
  17    Automated tests.
  18
  19    To run tests via the ``Makefile``.
  20
  21    Test the command line application.
  22
  23    .. code-block::
  24
  25       make test PYTHON_BIN=/path/to/bin/python3.11
  26
  27    If your system Python is v3.11 or newer you may omit ``PYTHON_BIN``.
  28
  29    .. code-block::
  30
  31       make test_blender BLENDER_BIN=/path/to/blender
  32
  33
  34 GUI
  35 ===
  36
  37 This GUI is work-in-progress, currently it's been made to work with an un-modified Blender 4.1.
  38
  39 - Link ``blender_addon/bl_pkg`` into your add-ons directly.
  40 - Enable the blender extensions add-on from Blender.
  41 - Enable the blender extensions checkbox in the add-ons preference (this is a temporary location).
  42 - Repositories can be added/removed from the "Files" section in the preferences.
  43
  44
  45 Hacking
  46 =======
  47
  48 Some useful hints.
  49
  50 When developing the command line interface, these tests can be setup to run on file-change, run:
  51
  52 .. code-block::
  53
  54    make watch_test
  55
  56 To run Blender tests.
  57
  58 .. code-block::
  59
  60    make watch_test_blender BLENDER_BIN=/path/to/blender
  61
  62 How to Setup a Test Environment
  63 ===============================
  64
  65 Most of the options here are using the command-line tools. For a comprehensive list of commands check the help:
  66
  67 .. code-block::
  68
  69    ./blender_addon/bl_pkg/cli/blender_ext.py --help
  70
  71
  72 Dummy server
  73 ------------
  74
  75 The simple way to get started is by creating a dummy asset library.
  76
  77 .. code-block::
  78
  79    ./blender_addon/bl_pkg/cli/blender_ext.py dummy-repo \
  80       --repo-dir=/path/to/host/my/repo/files \
  81       --package-names="blue,red,green,purple,orange"
  82
  83 This will populate the directory specified as ``--repo-dir`` with dummy assets packages (``.zip``),
  84 and an index (``bl_ext_repo.json``).
  85
  86
  87 Setup an Extensions Repository
  88 ==============================
  89
  90 First you need to create individual packages for the individual extension:
  91
  92 - Go to the directory of the extension you want to package.
  93 - Create a ``bl_ext_pkg.toml`` file with your configuration.
  94 - Run the command ``blender_ext.py build``.
  95
  96 You can look at an example of a dummy extension in the ``example_extension`` directory.
  97
  98 .. code-block::
  99
 100    cd ./example_extension
 101    ../blender_addon/bl_pkg/cli/blender_ext.py build
 102
 103 This will create a ``my_example_package.zip`` (as specified in the .toml file).
 104
 105 Now you can move all your ``*.zip`` packages to where they will be hosted in the server.
 106 The final step is to create an index file to serve all your packages.
 107
 108 .. code-block::
 109
 110    mkdir -p /path/to/host/my/repo/files
 111    cp ./example_extension/my_example_package.zip /path/to/host/my/repo/files
 112    ./blender_addon/bl_pkg/cli/blender_ext.py server-generate --repo-dir /path/to/host/my/repo/files
 113
 114 This will generate a new file ``bl_ext_repo.json`` in your repository directory.
 115 This file is to be used the entry point to your remote server.
 116
 117 Alternatively, if you are doing tests locally,
 118 you can point the directory containing this file as the ``Remote Path`` to your Extensions Repository.
 119
 120
 121 .. This section could go elsewhere, for now there is only a single note.
 122
 123 Requirement: Add-Ons
 124 ====================
 125
 126 Add-ons packaged as extensions must use relative imports when importing its own sub-modules.
 127 This is a requirement of Python module name-spacing.
 128
 129
 130 Requirement: Blender 4.2
 131 ========================
 132
 133 This add-on requires an yet-to-be released version of Blender.
 134
 135 You can download a `daily build <https://builder.blender.org>`__ of Blender 4.2 for testing and development purposes.