debug.dart 3.91 KB
Newer Older
Ian Hickson's avatar
Ian Hickson committed
1
// Copyright 2014 The Flutter Authors. All rights reserved.
2 3 4
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

5
import 'dart:ui' as ui show Brightness;
6

7
import 'assertions.dart';
8
import 'platform.dart';
9
import 'print.dart';
10 11 12 13 14 15 16 17 18 19 20 21

/// Returns true if none of the foundation library debug variables have been
/// changed.
///
/// This function is used by the test framework to ensure that debug variables
/// haven't been inadvertently changed.
///
/// The `debugPrintOverride` argument can be specified to indicate the expected
/// value of the [debugPrint] variable. This is useful for test frameworks that
/// override [debugPrint] themselves and want to check that their own custom
/// value wasn't overridden by a test.
///
22 23
/// See [the foundation library](foundation/foundation-library.html)
/// for a complete list.
24
bool debugAssertAllFoundationVarsUnset(String reason, { DebugPrintCallback debugPrintOverride = debugPrintThrottled }) {
25
  assert(() {
26
    if (debugPrint != debugPrintOverride ||
27
        debugDefaultTargetPlatformOverride != null ||
28 29
        debugDoublePrecision != null ||
        debugBrightnessOverride != null)
30
      throw FlutterError(reason);
31
    return true;
32
  }());
33 34
  return true;
}
35

36 37 38 39 40 41 42 43 44 45 46
/// Boolean value indicating whether [debugInstrumentAction] will instrument
/// actions in debug builds.
bool debugInstrumentationEnabled = false;

/// Runs the specified [action], timing how long the action takes in debug
/// builds when [debugInstrumentationEnabled] is true.
///
/// The instrumentation will be printed to the logs using [debugPrint]. In
/// non-debug builds, or when [debugInstrumentationEnabled] is false, this will
/// run [action] without any instrumentation.
///
47 48 49 50
/// Returns the result of running [action].
///
/// See also:
///
51 52 53
///  * [Timeline], which is used to record synchronous tracing events for
///    visualization in Chrome's tracing format. This method does not
///    implicitly add any timeline events.
54
Future<T> debugInstrumentAction<T>(String description, Future<T> Function() action) async {
55
  bool instrument = false;
56 57 58 59
  assert(() {
    instrument = debugInstrumentationEnabled;
    return true;
  }());
60
  if (instrument) {
61
    final Stopwatch stopwatch = Stopwatch()..start();
62 63 64
    try {
      return await action();
    } finally {
65 66
      stopwatch.stop();
      debugPrint('Action "$description" took ${stopwatch.elapsed}');
67
    }
68 69
  } else {
    return action();
70 71 72
  }
}

73 74 75
/// Argument passed to [dart:developer.Timeline] events in order to cause those
/// events to be shown in the developer-centric version of the Observatory
/// Timeline.
Ian Hickson's avatar
Ian Hickson committed
76
///
77 78
/// Generally these indicate landmark events such as the build phase or layout.
///
Ian Hickson's avatar
Ian Hickson committed
79 80
/// See also:
///
81 82
///  * [dart:developer.Timeline.startSync], which typically takes this value as
///    its `arguments` argument.
83
const Map<String, String> timelineArgumentsIndicatingLandmarkEvent = <String, String>{
84
  'mode': 'basic',
85
};
86 87 88 89

/// Configure [debugFormatDouble] using [num.toStringAsPrecision].
///
/// Defaults to null, which uses the default logic of [debugFormatDouble].
90
int? debugDoublePrecision;
91 92 93

/// Formats a double to have standard formatting.
///
94
/// This behavior can be overridden by [debugDoublePrecision].
95
String debugFormatDouble(double? value) {
96 97 98 99
  if (value == null) {
    return 'null';
  }
  if (debugDoublePrecision != null) {
100
    return value.toStringAsPrecision(debugDoublePrecision!);
101 102 103
  }
  return value.toStringAsFixed(1);
}
104 105

/// A setting that can be used to override the platform [Brightness] exposed
106
/// from [BindingBase.platformDispatcher].
107 108 109 110 111
///
/// See also:
///
///  * [WidgetsApp], which uses the [debugBrightnessOverride] setting in debug mode
///    to construct a [MediaQueryData].
112
ui.Brightness? debugBrightnessOverride;
113 114 115 116

/// The address for the active DevTools server used for debugging this
/// application.
String? activeDevToolsServerAddress;
117 118 119

/// The uri for the connected vm service protocol.
String? connectedVmServiceUri;