com.oracle.truffle.tools.debug.shell.package-info Maven / Gradle / Ivy
/*
* Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
/*
@ApiInfo(
group="Tools & Extras"
)
*/
/**
* This package contains REPL*: an experimental framework for
* building a language-agnostic command-line oriented debugger that:
*
* - works with every Truffle-implemented language "out of the box",
* i.e. requiring minimal additional support by language implementors;
* - works simultaneously, without special configuration, for all Truffle language implementations
* available to it; and
* - demonstrates Truffle language-interopability by debugging seamlessly
* across Truffle cross-language calls.
*
*
*
Goals for building REPL*
*
* - Exercise and test in action the built-in
* {@linkplain com.oracle.truffle.api.debug.Debugger} debugging support services
* provided as part of the Truffle API, which in turn relies on Truffle
* {@linkplain com.oracle.truffle.api.instrument.Instrumenter Instrumentation}.
* - Emulates a client/server architecture to demonstrate that
* language-agnostic debugging can be implemented over wire protocols. Wire
* protocol communication between client and server is partially emulated
* by passing messages expressed as textual key-value pairs. The emulation is
* partial because both run interleaved on a single JVM thread, with some
* sharing of resources.
* - Provide a working debugger that is always available during development
* of new Truffle language implementations.
* - Provide a working debugger with extra support for Truffle language
* development, in particular the ability to inspect the current structure
* of the Truffle AST around a halted location.
*
* Command Set
* The Command Line Interface (CLI) for REPL* is based as
* much as possible on the CLI for the
* GDB Debugger.
* REPL* Functionality
* Basic navigation:
*
* - StepIn (n times)
* - StepOut (n times)
* - StepOver (n times)
*
* Execution:
*
* - Load a file source
* - Call a defined symbol
*
* Stack:
*
* - List frames in current execution stack
* - Select a frame
* - Display selected frame contents
* - Move frame selection up/down
*
* Evaluate:
*
* - Evaluate a Language string in halted context
* - Evaluate a Language string in selected frame
*
* Breakpoints:
*
* - Set/create on a specified line
* - Set/create on any throw (before exception created)
* - Enable / Disable
* - One-shot (once only)
* - Get Hit count
* - Set Ignore count
* - Unset/dispose
* - Get all breakpoints
* - Find a breakpoint by UID
* - Set/clear the condition on a breakpoint
*
* Others:
*
* - Display halted location in source
* - Nested execution
*
- Help
* - Info displays
* - Set/display options
* - Display Truffle AST structure
*
*/
package com.oracle.truffle.tools.debug.shell;