Add DEFINE_CONST_OBJ_TYPE note.

Build-Troubleshooting.md

@@ -1,3 +1,65 @@
-# Submodules
+(This page is a work-in-progress! Much more to come.)
+
+# Core MicroPython
+
+## DEFINE_CONST_OBJ_TYPE
+
+If you see errors involving the `DEFINE_CONST_OBJ_TYPE` macro, or anything to do with the definition of `mp_obj_type_t` then see #8813. You will need to update any definition of types in your custom modules from:
+
+```c
+const mp_obj_type_t mp_type_foo = {
+    { &mp_type_type },
+    .name = MP_QSTR_foo,
+    .print = array_print,
+    .make_new = array_make_new,
+    ...
+    locals_dict, &mp_obj_array_locals_dict,
+};
+```
+
+to
+
+```c
+MP_DEFINE_CONST_OBJ_TYPE(
+    mp_type_array,
+    MP_QSTR_array,
+    MP_TYPE_FLAG_NONE,
+    print, array_print,
+    make_new, array_make_new,
+    ...
+    locals_dict, &mp_obj_array_locals_dict
+);
+```
+
+Note that a trailing comma after the last argument is not allowed.
+
+The first three arguments (symbol name, type name QSTR, flags) are required, and then a variable number of "slots" can be specified. If you don't have any flags (most types), then use `MP_TYPE_FLAG_NONE`.
+
+## getiter/iternext
+
+If you see errors about `getiter` and/or `iternext` then also see #8813.
+
+In order to save space, the `getiter` and `iternext` slots were merged on `mp_obj_type_t`. The following changes need to be made to your object type definitions.
+
+- If you previously had just a `getiter`, then no change is required.
+- If you had `getiter` as `mp_identity_getiter` and a custom `iternext`, then pass your iternext function to the `getiter` slot, and set the `MP_TYPE_FLAG_ITERNEXT` flag.
+- If you had `getiter` as `mp_identity_getiter` and `mp_stream_unbuffered_iter` as `iternext`, then just set the `MP_TYPE_FLAG_ITERNEXT_STREAM` and do not set the `getiter` slot.
+- If you had both a custom getiter and iternext, then you need to pass an instance of a `mp_getiter_iternext_custom_t` to the `getiter` slot and set the `MP_TYPE_FLAG_ITERNEXT_CUSTOM` flag. See [moduasyncio.c](https://github.com/micropython/micropython/blob/master/extmod/moduasyncio.c).
+
+# Dependencies
+
+## Submodules
+
+If you see compile errors about NimBLE, mbedtls, etc, then it's likely that the required submodules are not available. Run
+
+```
+make BOARD=... submodules
+```
+
+to automatically initialise required submodules.
 
 # Port specific
+
+## ESP32
+
+Check that you are using a [supported IDF version](https://github.com/micropython/micropython/tree/master/ports/esp32#setting-up-esp-idf-and-the-build-environment). The build will not work with IDF v5.0.