Skip to content

Latest commit

 

History

History
224 lines (163 loc) · 7.33 KB

generate_modules.md

File metadata and controls

224 lines (163 loc) · 7.33 KB
Raw

Generate Modules

This document shows the procedure for generating modules by yourself.
You can choose the method to generate modules.

  1. Case 1: Use utility script
  2. Case 2: Do it yourself all procedures
  3. Case 3: Do Case 2 inside Docker

Pre-requirement

Python Version

The generating script can be run on Python >= 3.8. Check your Python version is >= 3.8.

Install requirement packages

The generating script uses the packages listed on requirements.txt.
Execute below command to install requirement packages.

git clone https://github.com/nutti/fake-bpy-module.git
cd fake-bpy-module
pip install -r src/requirements.txt

Setup IDE

After generating modules, you need to setup IDE to enable a code completion.

Case 1: Use utility script

1. Download Blender binary

Download Blender binary from Blender official download site. Download Blender whose version is the version you try to generate modules.

2. Download Blender sources

git clone https://projects.blender.org/blender/blender.git

3. Download fake-bpy-module sources

Download the fake-bpy-module sources from GitHub.

Use Git and clone fake-bpy-module repository.

git clone https://github.com/nutti/fake-bpy-module.git

Or, you can download .zip file from GitHub.

https://github.com/nutti/fake-bpy-module/archive/master.zip

4. Run script

cd fake-bpy-module/src
bash gen_module.sh <source-dir> <blender-dir> <target> <branch/tag/commit> <target-version> <output-dir> [<mod-version>]
  • <source-dir>: Specify Blender sources directory.
  • <blender-dir>: Specify Blender binary directory.
  • <target>: blender or upbge.
  • <branch/tag/commit>: Specify target Blender source's branch for the generating modules.
    • If you want to generate modules for 2.79, specify v2.79
    • If you want to generate modules for newest Blender version, specify main
  • <target-version>: Specify target version.
  • <output-dir>: Specify directory where generated modules are output.
  • <mod-version>: Modify APIs by using patch files located in mods directory.
    • If you specify 2.80, all patch files under mods/2.80 will be used.
    • Files located in mods/common directories will be used at any time.

Specify Python interpreter

By default, this command uses Python interpreter by calling python command.
If you want to use other Python interpreter, you can specify by PYTHON_BIN environment variable.

PYTHON_BIN=/path/to/python3.8 bash gen_module.sh <source-dir> <blender-dir> <target> <branch/tag/commit> <target-version> <output-dir> [<mod-version>]

Case 2: Do it yourself all procedures

1. Download Blender binary

Download Blender binary from Blender official download site.
Download Blender whose version is the version you try to generate modules.
Place Blender binary to some directory.
In this tutorial, Blender binary assumes to be placed on /workspace/blender-bin. (i.e. Blender executable is located on /workspace/blender-bin/blender)

export WORKSPACE=/workspace
export BLENDER_BIN=${WORKSPACE}/blender-bin
export BLENDER_SRC=${WORKSPACE}/blender

2. Download Blender sources

cd ${WORKSPACE}
git clone https://projects.blender.org/blender/blender.git

3. Change to the target branch/tag/commit

Be sure to match the version between sources and binary. If you try to generate modules for v2.79, you should use git checkout v2.79.

cd ${BLENDER_SRC}
git checkout [branch/tag/commit]

4. Generate .rst documents

Generated .rst documents are located on ${BLENDER_SRC}/doc/python_api/sphinx-in.

${BLENDER_BIN}/blender --background --factory-startup -noaudio --python-exit-code 1 --python doc/python_api/sphinx_doc_gen.py

5. Download fake-bpy-module sources

Download the fake-bpy-module sources from GitHub.

Use Git and clone fake-bpy-module repository.

cd ${WORKSPACE}
git clone https://github.com/nutti/fake-bpy-module.git

Or, you can download .zip file from GitHub.

https://github.com/nutti/fake-bpy-module/archive/master.zip

6. Generate mod files

cd fake-bpy-module/src

mkdir -p mods/generated_mods
${BLENDER_BIN}/blender --background --factory-startup -noaudio --python-exit-code 1 --python gen_modfile/gen_external_modules_modfile.py -- -m addon_utils -o mods/generated_mods/gen_modules_modfile -f json
${BLENDER_BIN}/blender --background --factory-startup -noaudio --python-exit-code 1 --python gen_modfile/gen_external_modules_modfile.py -- -m keyingsets_builtins -a -o mods/generated_mods/gen_startup_modfile -f json

mkdir -p mods/generated_mods/gen_bgl_modfile
python gen_modfile/gen_bgl_modfile.py -i ${BLENDER_SRC}/source/blender/python/generic/bgl.cc -o mods/generated_mods/gen_bgl_modfile/bgl.json -f json

7. Generate modules

python gen.py -i <input-dir> -o <output-dir> -f <format> -T <target> -t <target-version> -m <mod-version>
  • -i <input-dir>: Specify input directory (The directory where .rst files are located in process 4). In this document, <input-dir> should be ${BLENDER_SRC}/doc/python_api/sphinx-in.
  • -o <output-dir>: Specify output directory. (The directory where generated files will be located)
  • -d: Dump internal data structures to <output-dir> as the files name with suffix -dump.json
  • -f <format>: Format the generated code by <format> convention.
    • none: Don't format generated code.
    • yapf: Format generated code with yapf.
    • ruff: Format generated code with ruff.
  • -T <target>: Target (blender or upbge).
  • -t <target-version>: Specify target version.
  • -m <mod-version>: Modify APIs by using patch files located in mods directory.
    • If you specify 2.80, all patch files under mods/2.80 will be used.
    • Files located in mods/common directories will be used at any time.

Case 3: Do Case 2 inside Docker

Run script

bash tools/gen_module/run_gen_module_in_docker.sh <blender-version>
  • <blender-version>: Specify blender version.

<mod-version> is automatically determined by <blender-version> version.

Results

Directory Contents
build/blender-bin Blender binaries
build/blender-src Blender source code
build/examples Blender Python API sample code
build/results Result *.pyi files
build/sphinx-in Blender Python API documents
build/sphinx-in-tmp ???
downloads Blender archives