debug.dart 4.15 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
export 'dart:ui' show Brightness;

export 'print.dart' show DebugPrintCallback;

15 16 17 18 19 20 21 22 23 24 25
/// 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.
///
26 27
/// See [the foundation library](foundation/foundation-library.html)
/// for a complete list.
28
bool debugAssertAllFoundationVarsUnset(String reason, { DebugPrintCallback debugPrintOverride = debugPrintThrottled }) {
29
  assert(() {
30
    if (debugPrint != debugPrintOverride ||
31
        debugDefaultTargetPlatformOverride != null ||
32
        debugDoublePrecision != null ||
33
        debugBrightnessOverride != null) {
34
      throw FlutterError(reason);
35
    }
36
    return true;
37
  }());
38 39
  return true;
}
40

41 42
/// Boolean value indicating whether [debugInstrumentAction] will instrument
/// actions in debug builds.
Ian Hickson's avatar
Ian Hickson committed
43 44 45 46 47 48 49 50 51 52 53 54
///
/// The framework does not use [debugInstrumentAction] internally, so this
/// does not enable any additional instrumentation for the framework itself.
///
/// See also:
///
///  * [debugProfileBuildsEnabled], which enables additional tracing of builds
///    in [Widget]s.
///  * [debugProfileLayoutsEnabled], which enables additional tracing of layout
///    events in [RenderObject]s.
///  * [debugProfilePaintsEnabled], which enables additional tracing of paint
///    events in [RenderObject]s.
55 56 57 58 59 60 61 62 63
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.
///
64 65 66 67
/// Returns the result of running [action].
///
/// See also:
///
68 69 70
///  * [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.
71
Future<T> debugInstrumentAction<T>(String description, Future<T> Function() action) async {
72
  bool instrument = false;
73 74 75 76
  assert(() {
    instrument = debugInstrumentationEnabled;
    return true;
  }());
77
  if (instrument) {
78 79
    final Stopwatch stopwatch = Stopwatch()..start(); // flutter_ignore: stopwatch (see analyze.dart)
    // Ignore context: The framework does not use this function internally so it will not cause flakes.
80 81 82
    try {
      return await action();
    } finally {
83 84
      stopwatch.stop();
      debugPrint('Action "$description" took ${stopwatch.elapsed}');
85
    }
86 87
  } else {
    return action();
88 89 90
  }
}

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

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

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

/// The address for the active DevTools server used for debugging this
/// application.
String? activeDevToolsServerAddress;
121 122 123

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