summaryrefslogtreecommitdiffstats
path: root/bitbake/lib/bb
diff options
context:
space:
mode:
authorPaul Eggleton <paul.eggleton@linux.intel.com>2017-07-19 11:56:09 +0200
committerRichard Purdie <richard.purdie@linuxfoundation.org>2017-07-21 08:41:12 +0100
commit2b5c3617c2779d7b13afe91bcc07f8b6057be1e7 (patch)
tree18adabe54e8c8a0ea6382c7cded782c67a91b992 /bitbake/lib/bb
parent388ae704bbd5116cfba517177b109fb18377f0e2 (diff)
downloadpoky-2b5c3617c2779d7b13afe91bcc07f8b6057be1e7.tar.gz
bitbake: tinfoil: add more doc comments
We want this API to be easier to use, so add missing function documentation to help with that. (Bitbake rev: 3e0e002d6497caa987f327cd83ad4db82cca6810) Signed-off-by: Paul Eggleton <paul.eggleton@linux.intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'bitbake/lib/bb')
-rw-r--r--bitbake/lib/bb/tinfoil.py65
1 files changed, 65 insertions, 0 deletions
diff --git a/bitbake/lib/bb/tinfoil.py b/bitbake/lib/bb/tinfoil.py
index 30d6c9af3e..e246b3d2a2 100644
--- a/bitbake/lib/bb/tinfoil.py
+++ b/bitbake/lib/bb/tinfoil.py
@@ -55,6 +55,7 @@ class TinfoilCommandFailed(Exception):
55 """Exception raised when run_command fails""" 55 """Exception raised when run_command fails"""
56 56
57class TinfoilDataStoreConnector: 57class TinfoilDataStoreConnector:
58 """Connector object used to enable access to datastore objects via tinfoil"""
58 59
59 def __init__(self, tinfoil, dsindex): 60 def __init__(self, tinfoil, dsindex):
60 self.tinfoil = tinfoil 61 self.tinfoil = tinfoil
@@ -294,8 +295,25 @@ class TinfoilRecipeInfo:
294 295
295 296
296class Tinfoil: 297class Tinfoil:
298 """
299 Tinfoil - an API for scripts and utilities to query
300 BitBake internals and perform build operations.
301 """
297 302
298 def __init__(self, output=sys.stdout, tracking=False, setup_logging=True): 303 def __init__(self, output=sys.stdout, tracking=False, setup_logging=True):
304 """
305 Create a new tinfoil object.
306 Parameters:
307 output: specifies where console output should be sent. Defaults
308 to sys.stdout.
309 tracking: True to enable variable history tracking, False to
310 disable it (default). Enabling this has a minor
311 performance impact so typically it isn't enabled
312 unless you need to query variable history.
313 setup_logging: True to setup a logger so that things like
314 bb.warn() will work immediately and timeout warnings
315 are visible; False to let BitBake do this itself.
316 """
299 self.logger = logging.getLogger('BitBake') 317 self.logger = logging.getLogger('BitBake')
300 self.config_data = None 318 self.config_data = None
301 self.cooker = None 319 self.cooker = None
@@ -316,6 +334,37 @@ class Tinfoil:
316 self.shutdown() 334 self.shutdown()
317 335
318 def prepare(self, config_only=False, config_params=None, quiet=0, extra_features=None): 336 def prepare(self, config_only=False, config_params=None, quiet=0, extra_features=None):
337 """
338 Prepares the underlying BitBake system to be used via tinfoil.
339 This function must be called prior to calling any of the other
340 functions in the API.
341 NOTE: if you call prepare() you must absolutely call shutdown()
342 before your code terminates. You can use a "with" block to ensure
343 this happens e.g.
344
345 with bb.tinfoil.Tinfoil() as tinfoil:
346 tinfoil.prepare()
347 ...
348
349 Parameters:
350 config_only: True to read only the configuration and not load
351 the cache / parse recipes. This is useful if you just
352 want to query the value of a variable at the global
353 level or you want to do anything else that doesn't
354 involve knowing anything about the recipes in the
355 current configuration. False loads the cache / parses
356 recipes.
357 config_params: optionally specify your own configuration
358 parameters. If not specified an instance of
359 TinfoilConfigParameters will be created internally.
360 quiet: quiet level controlling console output - equivalent
361 to bitbake's -q/--quiet option. Default of 0 gives
362 the same output level as normal bitbake execution.
363 extra_features: extra features to be added to the feature
364 set requested from the server. See
365 CookerFeatures._feature_list for possible
366 features.
367 """
319 self.quiet = quiet 368 self.quiet = quiet
320 369
321 if self.tracking: 370 if self.tracking:
@@ -440,9 +489,16 @@ class Tinfoil:
440 return self.server_connection.events.waitEvent(timeout) 489 return self.server_connection.events.waitEvent(timeout)
441 490
442 def get_overlayed_recipes(self): 491 def get_overlayed_recipes(self):
492 """
493 Find recipes which are overlayed (i.e. where recipes exist in multiple layers)
494 """
443 return defaultdict(list, self.run_command('getOverlayedRecipes')) 495 return defaultdict(list, self.run_command('getOverlayedRecipes'))
444 496
445 def get_skipped_recipes(self): 497 def get_skipped_recipes(self):
498 """
499 Find recipes which were skipped (i.e. SkipRecipe was raised
500 during parsing).
501 """
446 return OrderedDict(self.run_command('getSkippedRecipes')) 502 return OrderedDict(self.run_command('getSkippedRecipes'))
447 503
448 def get_all_providers(self): 504 def get_all_providers(self):
@@ -475,6 +531,9 @@ class Tinfoil:
475 return best[3] 531 return best[3]
476 532
477 def get_file_appends(self, fn): 533 def get_file_appends(self, fn):
534 """
535 Find the bbappends for a recipe file
536 """
478 return self.run_command('getFileAppends', fn) 537 return self.run_command('getFileAppends', fn)
479 538
480 def all_recipes(self, mc='', sort=True): 539 def all_recipes(self, mc='', sort=True):
@@ -739,6 +798,12 @@ class Tinfoil:
739 return ret 798 return ret
740 799
741 def shutdown(self): 800 def shutdown(self):
801 """
802 Shut down tinfoil. Disconnects from the server and gracefully
803 releases any associated resources. You must call this function if
804 prepare() has been called, or use a with... block when you create
805 the tinfoil object which will ensure that it gets called.
806 """
742 if self.server_connection: 807 if self.server_connection:
743 self.run_command('clientComplete') 808 self.run_command('clientComplete')
744 _server_connections.remove(self.server_connection) 809 _server_connections.remove(self.server_connection)