Page MenuHome

Proposal: BKE_library and BKE_main API naming: prefixes conventions
Closed, ResolvedPublicDESIGN


The purpose of this task is not to actually rename all our functions in those headers right now. But rather to define (and document, in a comment in those headers) proper rules for the BKE_xxx prefixes we should use for these 'public' APIs.

In the past years, me and the few other devs that had to work in that area tried to sanitize a bit old names, but looking at current code state I have the feeling this was at best a mixed success so far.

Current situation

Besides old, never-yet-renamed functions, currently we seem to motsly follow those rules for new/renamed functions:

BKE_main.h (affecting Main structure itself)BKE_main_
BKE_library.h (ID management)low-level ID-onlyBKE_libblock_Those are ID-generic functions
data-block levelBKE_id_Those take into account the type of data-blocks
Main levelBKE_main_id_Those potentially affect all data-blocks in given bmain
Library data-blocksBKE_library_Those are specific to Library data-blocks
BKE_library_query.h (queries over Main database)BKE_library_
BKE_library_remap.h (remapping of IDs)Actual remappingBKE_libblock_Those are ID-generic functions
CallbacksBKE_library_callback_For ID users outside of Main area
BKE_library_idmap.h (mapping from ID type/name to id)BKE_main_idmap_Only used in reafile.c for in undo code currently
BKE_library_override.h (library overrides)On a single IDBKE_override_library_
On the whole MainBKE_main_override_library_


  • BKE_library_idmap.h should really be name BKE_main_idmap.h, this is not really related to ID management (though it could be useful there in some cases), this is just an alternative 'view' of given Main content.
  • library is a confusing term, since it is used for both a specific datablock type, and as the generic ID management word.
  • libblock (when only considering the actual generic ID part of a data-block) versus id (when considering the whole data-block, including its type-specific stuff) is rather confusing and somewhat misleading. Also because we do not use libblock wording anywhere else in Blender codebase afaik. Not sure we’d benefit much about changing that now though, given how deep those functions go allover Blender codebase?


First, rename BKE_library_idmap.h to BKE_main_idmap.h (and same for the .c implementation of course).
Then rename BKE_library files to use BKE_lib prefix instead (changing BKE_library.h to BKE_lib_id.h to avoid having too common/collision-risky name).
Finally split out Library data-blocks-specific functions into their own BKE_library file.

Then document this convention in respective headers, based on following principles:

  • File naming scope:
    • BKE_main files are for operations over the Main database itself, or generating extra temp data to help working with it. Those should typically not affect the data-blocks themselves.
    • BKE_library files are for operations over data-blocks themselves, although they might alter Main as well (when creating/Renaming/deleting an ID e.g.).
  • Use a common small prefix referring to a same header file:
    • BKE_main_ is kind of obvious.
    • BKE_lib_ for all the BKE_library files, to keep it short, and distinguish it from actual Library data-block specific code.
BKE_main.h (affecting Main structure itself)BKE_main_->BKE_main_
BKE_main_idmap.h (mapping from ID type/name to id)BKE_main_idmap_->BKE_main_idmap_
BKE_lib_id.h (ID management)low-level ID-onlyBKE_libblock_->BKE_lib_libblock_
data-block levelBKE_id_->BKE_lib_id_
Main levelBKE_main_id_->BKE_lib_main_
BKE_lib_query.h (queries over Main database)BKE_library_->BKE_lib_query_
BKE_lib_remap.h (remapping of IDs)Actual remappingBKE_libblock_->BKE_lib_remap_libblock_
BKE_lib_override.h (library overrides)On a single IDBKE_override_library_->BKE_lib_override_library_
On the whole MainBKE_main_override_library_->BKE_lib_override_library_main_
BKE_library.h (Library IDs)Library data-blocksBKE_library_->BKE_library_

This should be enforced for all new functions added there, as well as any future cleanup/renaming.

Event Timeline

Bastien Montagne (mont29) triaged this task as Low priority.Dec 20 2019, 4:04 PM
Bastien Montagne (mont29) created this task.

Note that this is an initial draft, am not happy with all proposed new names,. E.g. the override case is a bit hairy, since we end up using library for two different meaning (lib, as 'par of ID management code`, and in library override, i.e. 'override of linked data-blocks' [opposed to 'dynamic override']), none of them being fully related to actual Library data-block itself…

Proposal sounds good to me.

One extra possible step is to split BKE_library perhaps. Just to add some separation between allocate new ID block and operations on Library. But that's another story :)

Well thought through, not much to add.

Minor preference to use the lib abbreviation for file naming too: BLI_lib.h BLI_lib_remap.h - we mostly stick to the same convention, so I think it's nice to keep this.

Quick question: if we rename BKE_library to BKE_lib, do we want BKE_lib.h/lib.c (I guess not), or something like e.g. BKE_lib_id.h/lib_id.c ?

Agree having lib.c - is too likely to collide w/ other names, BKE_lib_id.h/lib_id.c LGTM.

@Campbell Barton (campbellbarton) thanks, also talked to @Brecht Van Lommel (brecht) here and he was fine with BKE_lib_id as well, so there we go.

Bastien Montagne (mont29) closed this task as Resolved.Mar 4 2020, 6:03 PM

Think we can close this now, changes at high-level have been approved and done, functions renaming will happen on case-by-case approach.