diff --git a/src/blenderbim/blenderbim/__init__.py b/src/blenderbim/blenderbim/__init__.py index c5d6420273..e54b2d04ac 100644 --- a/src/blenderbim/blenderbim/__init__.py +++ b/src/blenderbim/blenderbim/__init__.py @@ -131,7 +131,7 @@ if sys.modules.get("bpy", None): box.label(text=f"Python {py} BBIM {info['blenderbim_version']}", icon="SCRIPTPLUGINS") layout.operator("bim.copy_debug_information", text="Copy Error Message To Clipboard") op = layout.operator("bim.open_uri", text="How Can I Fix This?") - op.uri = "https://docs.blenderbim.org/users/installation.html#faq" + op.uri = "https://docs.blenderbim.org/users/troubleshooting.html#installation-issues" class OpenUri(bpy.types.Operator): bl_idname = "bim.open_uri" diff --git a/src/blenderbim/blenderbim/bim/ui.py b/src/blenderbim/blenderbim/bim/ui.py index 7654062959..2b55904929 100644 --- a/src/blenderbim/blenderbim/bim/ui.py +++ b/src/blenderbim/blenderbim/bim/ui.py @@ -29,8 +29,9 @@ from ifcopenshell.util.doc import ( get_attribute_doc, ) from . import ifc -import blenderbim.tool as tool +from blenderbim import get_debug_info import blenderbim.bim +import blenderbim.tool as tool from blenderbim.bim.helper import IfcHeaderExtractor from blenderbim.bim.prop import Attribute @@ -402,6 +403,15 @@ class BIM_PT_tabs(Panel): row = self.layout.row(align=True) row.prop(aprops, "tab", text="") + + if blenderbim.last_error: + box = self.layout.box() + box.label(text="BlenderBIM experienced an error :(", icon="ERROR") + box.label(text="View the console for full logs.", icon="CONSOLE") + box.operator("bim.copy_debug_information", text="Copy Error Message To Clipboard") + op = box.operator("bim.open_uri", text="How Can I Fix This?") + op.uri = "https://docs.blenderbim.org/users/troubleshooting.html" + except: pass # Prior to load_post, we may not have any area properties setup diff --git a/src/blenderbim/docs/devs/installation.rst b/src/blenderbim/docs/devs/installation.rst index 96ee05e206..bda42056bc 100644 --- a/src/blenderbim/docs/devs/installation.rst +++ b/src/blenderbim/docs/devs/installation.rst @@ -13,9 +13,9 @@ Unstable installation **Unstable installation** is almost the same as **Stable installation**, except that they are typically updated every day. Simply download a daily build from -the `Github releases page -`__, then follow the same -instructions as the **Stable installation**. +the `GitHub releases page +`__, then follow the +usual :doc:`installation instructions`. You will need to choose which build to download. diff --git a/src/blenderbim/docs/index.rst b/src/blenderbim/docs/index.rst index b8f21e5a6b..7d6b439721 100644 --- a/src/blenderbim/docs/index.rst +++ b/src/blenderbim/docs/index.rst @@ -32,6 +32,7 @@ Learn how to model a small building and create simple architectural plans, secti users/git_support users/other_addons users/general_usage + users/troubleshooting .. toctree:: :hidden: diff --git a/src/blenderbim/docs/users/images/error-message.png b/src/blenderbim/docs/users/images/error-message.png new file mode 100644 index 0000000000..bdc1ce38f0 Binary files /dev/null and b/src/blenderbim/docs/users/images/error-message.png differ diff --git a/src/blenderbim/docs/users/installation.rst b/src/blenderbim/docs/users/installation.rst index 95a6099913..bbcd8fe7c8 100644 --- a/src/blenderbim/docs/users/installation.rst +++ b/src/blenderbim/docs/users/installation.rst @@ -58,51 +58,6 @@ You can enable add-ons permanently by using ``Save User Settings`` from the Addo .. _where is the add-on installed: -Where is the add-on installed? ------------------------------- - -Upon installation, the BlenderBIM Add-on is stored in the -``scripts/addons/blenderbim/`` directory, within your Blender configuration -folder. However, the location of your Blender configuration folder depends on -how you have installed Blender. - -If you downloaded Blender as a ``.zip`` file without running an installer, you -will find the Blender configuration folder in the following directory, where -``X.XX`` is the Blender version: -:: - - /path/to/blender/X.XX/ - -Otherwise, if you installed Blender using an installation package, the Blender -configuration folder depends on which operating system you use. - -On Linux, if you are installing the add-on as a user: -:: - - ~/.config/blender/X.XX/ - -On Linux, if you are deploying the add-on system-wide (this may also depend on -your Linux distribution): -:: - - /usr/share/blender/X.XX/ - -On Mac, if you are installing the add-on as a user: -:: - - /Users/{YOUR_USER}/Library/Application Support/Blender/X.XX/ - -On Mac, if you are deploying the add-on system-wide: - -:: - - /Library/Application Support/Blender/X.XX/ - -On Windows: -:: - - C:\Users\{YOUR_USER}\AppData\Roaming\Blender Foundation\X.XX\ - Updating -------- @@ -129,66 +84,52 @@ installed>`. If you do not restart Blender, the add-on will fail to remove correctly, and you will need to uninstall manually. +Where is the add-on installed? +------------------------------ -FAQ ---- +Upon installation, the BlenderBIM Add-on is stored in the +``scripts/addons/blenderbim/`` directory, within your Blender configuration +folder. However, the location of your Blender configuration folder depends on +how you have installed Blender. -If you are unable to install the BlenderBIM Add-on, make sure you are using -**Blender 4.1** installed from https://blender.org/ and are installing the -latest version from https://blenderbim.org. +If you downloaded Blender as a ``.zip`` file without running an installer, the +BlenderBIM Add-on will be installed in the following directory, where ``X.XX`` +is the Blender version: -Other common solutions are listed below. If none of these fix the problem, you -can `report a bug `_ or -`live chat with a developer `_. +:: -1. **Some other error prevents me from installing or doing basic functions with - the add-on. Is it specific to my environment?** + /path/to/blender/X.XX/scripts/addons/blenderbim/ - Try installing and using the BlenderBIM Add-on on a "clean environment". A - clean environment is a fresh Blender installation with no other add-ons - enabled with factory settings. +Otherwise, if you installed Blender using an installation package, the Blender +configuration folder depends on which operating system you use. - To quickly test in a clean environment, find your Blender configuration - folder based on the `where is the add-on installed`_ section. Rename the - folder from ``X.XX`` to something else like ``X.XX_backup``, then restart - Blender and try follow the installation instructions again. +On Linux, if you are installing the add-on as a user: - If this fixes your issue, consider disabling other add-ons one by one until - you find a conflict as a next step to isolating the issue. +:: -2. **I get an error similar to "ImportError: IfcOpenShell not built for 'linux/64bit/python3.10'"** + ~/.config/blender/X.XX/scripts/addons/blenderbim/ - If you are using a Mac, be sure to use the Mac Silicon version if you have a - newer Mac. The only exception is if you have installed Blender using Steam - on a Mac, in which case you need to use the Mac Intel download. +On Linux, if you are deploying the add-on system-wide (this may also depend on +your Linux distribution): - For all other scenarios, check the BlenderBIM Add-on zip file which you - downloaded. The zip will have either ``py39``, ``py310``, or ``py311`` in - the name. See the instructions in the :ref:`devs/installation:unstable - installation` section to check that you have installed the correct version. +:: -3. **I am on Ubuntu and get an error similar to "ImportError: - /lib/x86_64-linux-gnu/libm.so.6: version GLIBC_2.29 not found"** + /usr/share/blender/X.XX/scripts/addons/blenderbim/ - Our latest package which uses IfcOpenShell v0.7.0 is built using Ubuntu 20 LTS. - If you have an older Ubuntu version, you can either upgrade to 19.10 or above, - or you'll need to compile IfcOpenShell yourself. +On Mac, if you are installing the add-on as a user: -4. **I get an error saying "ModuleNotFoundError: No module named 'numpy'"**" +:: - If you have installed Blender from another source instead of from - `Blender.org `__, such as from your - distro's package repositories, then you may be missing some modules like - ``numpy``. Try installing it manually like ``apt install python-numpy``. + /Users/{YOUR_USER}/Library/Application Support/Blender/X.XX/scripts/addons/blenderbim/ -5. **I get an error similar to RuntimeError: Instance #1234 not found** +On Mac, if you are deploying the add-on system-wide: - Blender saves and loads projects to a ``.blend`` file. However. the - BlenderBIM Add-on works with native IFC, and this means instead of saving - and loading ``.blend`` files, you should instead save and load the ``.ifc`` - project. +:: - If you have opened a ``.blend`` file, there is a risk that the contents of - the ``.blend`` session do not correlate to the contents of the ``.ifc``, - which can cause this error. Unless you are an advanced user, only save and - load ``.ifc`` files. + /Library/Application Support/Blender/X.XX/scripts/addons/blenderbim/ + +On Windows: + +:: + + C:\Users\{YOUR_USER}\AppData\Roaming\Blender Foundation\X.XX\scripts\addons\blenderbim\ diff --git a/src/blenderbim/docs/users/troubleshooting.rst b/src/blenderbim/docs/users/troubleshooting.rst new file mode 100644 index 0000000000..0115bc5d27 --- /dev/null +++ b/src/blenderbim/docs/users/troubleshooting.rst @@ -0,0 +1,93 @@ +Troubleshooting +=============== + +The BlenderBIM Add-on is alpha software. There are many bugs! When something +goes wrong, you may see some computer code flash up on your screen. You may +also see an error message: + +.. image:: images/error-message.png + +**Don't panic!** Click on the button that says **Copy Error Message To +Clipboard**. You will need to paste this text in a bug report. + +If you do not have a GitHub account, you will need to sign up to report a bug. +In addition to pasting the error message text, please also describe what you +were doing, and attach your IFC file or screenshots if relevant. + +.. container:: blockbutton + + `Report a bug `__ + +If your issue is particularly complex, you can also chat live with developers +or other powerusers. + +.. container:: blockbutton + + `Chat live with a developer `_ + +Installation issues +------------------- + +If you are unable to install the BlenderBIM Add-on, make sure you are using +**Blender 4.1** installed from https://blender.org/ and are installing the +latest version from https://blenderbim.org. + +Other common solutions are listed below. If none of these fix the problem, you +can `report a bug `_ or +`live chat with a developer `_. + +1. **Some other error prevents me from installing or doing basic functions with + the add-on. Is it specific to my environment?** + + Try installing and using the BlenderBIM Add-on on a "clean environment". A + clean environment is a fresh Blender installation with no other add-ons + enabled with factory settings. + + To quickly test in a clean environment, first :ref:`find your Blender + configuration folder`. + Rename the folder from ``X.XX`` to something else like ``X.XX_backup``, then + restart Blender and try follow the :doc:`installation + instructions` again. + + If this fixes your issue, consider disabling other add-ons one by one until + you find a conflict as a next step to isolating the issue. + +2. **I get an error similar to "ImportError: IfcOpenShell not built for 'linux/64bit/python3.10'"** + + If you are using a Mac, be sure to use the Mac Silicon version if you have a + newer Mac. The only exception is if you have installed Blender using Steam + on a Mac, in which case you need to use the Mac Intel download. + + For all other scenarios, check the BlenderBIM Add-on zip file which you + downloaded. The zip will have either ``py39``, ``py310``, or ``py311`` in + the name. See the instructions in the :ref:`devs/installation:unstable + installation` section to check that you have installed the correct version. + +3. **I am on Ubuntu and get an error similar to "ImportError: + /lib/x86_64-linux-gnu/libm.so.6: version GLIBC_2.29 not found"** + + Our latest package which uses IfcOpenShell v0.7.0 is built using Ubuntu 20 LTS. + If you have an older Ubuntu version, you can either upgrade to 19.10 or above, + or you'll need to compile IfcOpenShell yourself. + +4. **I get an error saying "ModuleNotFoundError: No module named 'numpy'"**" + + If you have installed Blender from another source instead of from + `Blender.org `__, such as from your + distro's package repositories, then you may be missing some modules like + ``numpy``. Try installing it manually like ``apt install python-numpy``. + +Common issues +------------- + +1. **I get an error similar to RuntimeError: Instance #1234 not found** + + Blender saves and loads projects to a ``.blend`` file. However. the + BlenderBIM Add-on works with native IFC, and this means instead of saving + and loading ``.blend`` files, you should instead save and load the ``.ifc`` + project. + + If you have opened a ``.blend`` file, there is a risk that the contents of + the ``.blend`` session do not correlate to the contents of the ``.ifc``, + which can cause this error. Unless you are an advanced user, only save and + load ``.ifc`` files.