From 337086d7f7a57bd4fde9fef02076af8c0f69f0ab Mon Sep 17 00:00:00 2001 From: Brecht Van Lommel Date: Wed, 5 Jun 2024 18:52:10 +0200 Subject: [PATCH 1/2] Advanced: New Deploying Blender page --- manual/advanced/blender_directory_layout.rst | 7 +- manual/advanced/deploying_blender.rst | 107 +++++++++++++++++++ manual/advanced/index.rst | 1 + 3 files changed, 112 insertions(+), 3 deletions(-) create mode 100644 manual/advanced/deploying_blender.rst diff --git a/manual/advanced/blender_directory_layout.rst b/manual/advanced/blender_directory_layout.rst index 6b13106c4..8d0501165 100644 --- a/manual/advanced/blender_directory_layout.rst +++ b/manual/advanced/blender_directory_layout.rst @@ -61,8 +61,8 @@ and presets. Environment Variables --------------------- -``BLENDER_USER`` :ref:`command-line-args-environment-variables` can be used to store -some or all configuration files in other directories. +``BLENDER_USER`` :ref:`environment variables ` +can be used to store some or all configuration files in other directories. This may be used for example when using a different configuration for a specific project, without affecting the regular user configuration. @@ -110,13 +110,14 @@ Microsoft Store installation: Environment Variables --------------------- -``BLENDER_SYSTEM`` :ref:`command-line-args-environment-variables` +``BLENDER_SYSTEM`` :ref:`environment variables ` can be used to bundle additional scripts and extensions, that are not part of the regular Blender installation. This can be used for example to deploy Blender in an animation studio, with additional add-ons available to all users. +.. _blender-directory-path-layout: Path Layout =========== diff --git a/manual/advanced/deploying_blender.rst b/manual/advanced/deploying_blender.rst new file mode 100644 index 000000000..3bf710e5d --- /dev/null +++ b/manual/advanced/deploying_blender.rst @@ -0,0 +1,107 @@ +.. _deploying-blender: + +***************** +Deploying Blender +***************** + +It is possible to deploy Blender in environments that are more +restricted, use automation or have other special requirements. +For example in an animation studio or for school courses. + +This page contains tips setting up Blender in such environments. + +Installing Blender +================== + +Blender downloads can be extracted to any directory on the system, as +a self contained installation. Multiple Blender versions can easily +co-exist on the same system, and deployment can be automated using +standard file management tools. + +New Blender versions may add, remove or changes functionality that +change the results of production files. For a given project, it is +advisable to use a single LTS (long term support) version of Blender. +LTS versions receive bug fixes for two years. + +Working Offline +=============== + +For security or other reasons, workstation may not have internet access. + +By default Blender does not access the internet, however this can be +enabled in the System preferences with the Online Access option. + +Working offline can be enforced by running with the ``--offline-mode`` +:ref:`command line argument `. + +Bundling Extensions +=================== + +When working offline or in a more controlled environment, it may be useful +to provide a set of extensions to all users. These can be served from a +read-only system repository. This repository could exist on a network drive +or in a system directory. + +The location of this system extension repository can be manually configured +in the Extensions preferences. + +The ``$BLENDER_SYSTEM_REPOSITORY`` +:ref:`environment variable ` +can also set the default location. This is a directory, within which a +``system`` directory should exist. Each extension zip file should be +extracted to its own folder, and which should then contain a +``blender_manifest.toml`` file. + +Bundling Scripts +================ + +Besides extensions, it's possible to bundle scripts for presets, +application templates, legacy add-ons, as well as scripts run on startup. + +Script directories can be manually added in the File Paths preferences. +The ``$BLENDER_SYSTEM_SCRIPTS`` can also be used to add a script directory +without modifying the preferences. + +These script directories are expected to contain specific directories +like ``presets``, ``addons`` and ``startup`` for different types of +scripts. See :ref:`blender-directory-path-layout` for a complete list. + +Startup Scripts +--------------- + +The Blender Python API can be used to customize Blender. This includes +changing preferences, changing the startup file and adding UI elements. + +For example a ``startup/enable_addons.py`` script can be created to +enable a set of add-ons for every user. + +.. code-block:: python + + def register(): + import addon_utils + addon_utils.enable("node_wrangler") + + def unregister(): + pass + + if __name__ == "__main__": + register() + +VFX Platform +============ + +Blender follows the `VFX reference platform `_, +which means it is able to run on the same systems as other VFX software +and exchange image, volume and scene files with them. + +Python Version +-------------- + +Blender and the `by module `_ are only compatible +with a single Python version. This makes it possible for add-ons and VFX software +in general to only have to target a single Python version. + +Blender bundles a complete Python installation and does not interact with the +system Python by default. This can be changed with the ``--python-use-system-env`` +:ref:`command line argument `, if care is +taken to set up a compatible Python version. diff --git a/manual/advanced/index.rst b/manual/advanced/index.rst index fc35653c5..b13c9442f 100644 --- a/manual/advanced/index.rst +++ b/manual/advanced/index.rst @@ -17,4 +17,5 @@ This chapter covers advanced use (topics which may not be required for typical u limits.rst operators.rst blender_directory_layout.rst + deploying_blender.rst appendices/index.rst -- 2.30.2 From 11dcba53910eb045573566f6c54751dc5dec85be Mon Sep 17 00:00:00 2001 From: Brecht Van Lommel Date: Fri, 7 Jun 2024 14:36:58 +0200 Subject: [PATCH 2/2] Clarify environment variables and paths --- manual/advanced/deploying_blender.rst | 31 ++++++++++++++++----------- 1 file changed, 19 insertions(+), 12 deletions(-) diff --git a/manual/advanced/deploying_blender.rst b/manual/advanced/deploying_blender.rst index 3bf710e5d..f4e94803d 100644 --- a/manual/advanced/deploying_blender.rst +++ b/manual/advanced/deploying_blender.rst @@ -1,8 +1,8 @@ .. _deploying-blender: -***************** -Deploying Blender -***************** +******************************* +Deploying Blender in Production +******************************* It is possible to deploy Blender in environments that are more restricted, use automation or have other special requirements. @@ -20,8 +20,8 @@ standard file management tools. New Blender versions may add, remove or changes functionality that change the results of production files. For a given project, it is -advisable to use a single LTS (long term support) version of Blender. -LTS versions receive bug fixes for two years. +advisable to use a single :abbr:`LTS (Long-Term-Support)` version +of Blender. LTS versions receive bug fixes for two years. Working Offline =============== @@ -32,7 +32,8 @@ By default Blender does not access the internet, however this can be enabled in the System preferences with the Online Access option. Working offline can be enforced by running with the ``--offline-mode`` -:ref:`command line argument `. +:ref:`command line argument `. Users +will then be unable to enable online access in the preferences. Bundling Extensions =================== @@ -45,12 +46,15 @@ or in a system directory. The location of this system extension repository can be manually configured in the Extensions preferences. -The ``$BLENDER_SYSTEM_REPOSITORY`` +The ``$BLENDER_SYSTEM_EXTENSIONS`` :ref:`environment variable ` can also set the default location. This is a directory, within which a -``system`` directory should exist. Each extension zip file should be -extracted to its own folder, and which should then contain a -``blender_manifest.toml`` file. +``system`` directory should exist. Then extract extension packages there, +with a resulting path like this: + +.. code-block:: bash + + $BLENDER_SYSTEM_EXTENSIONS/system/my-addon/blender_manifest.toml Bundling Scripts ================ @@ -72,8 +76,11 @@ Startup Scripts The Blender Python API can be used to customize Blender. This includes changing preferences, changing the startup file and adding UI elements. -For example a ``startup/enable_addons.py`` script can be created to -enable a set of add-ons for every user. +For example, a script can enable add-ons for every user. + +.. code-block:: bash + + $BLENDER_SYSTEM_SCRIPTS/startup/enable_addons.py .. code-block:: python -- 2.30.2