------------------------------------------------------------------------------- | |
-- Copyright (c) 2011-2012 Sierra Wireless and others. | |
-- All rights reserved. This program and the accompanying materials | |
-- are made available under the terms of the Eclipse Public License v1.0 | |
-- which accompanies this distribution, and is available at | |
-- http://www.eclipse.org/legal/epl-v10.html | |
-- | |
-- Contributors: | |
-- Sierra Wireless - initial API and implementation | |
------------------------------------------------------------------------------- | |
-- Debugger using DBGp protocol. | |
------------------------------------------------------------------------------- | |
-- The module returns a single init function which takes 7 parameters (IDEHOST, IDEPORT, IDEKEY, TRANSPORT, PLATFORM, WORKINGDIR, NBRETRY). | |
-- | |
-- IDEHOST: the host name or the ip address of the DBGP server (so your ide) | |
-- if HOST is nil, the DBGP_IDEHOST env var is used. | |
-- if the env var is nil, the default value '127.0.0.1' is used. | |
-- | |
-- IDEPORT: the port of the DBGP server (must be configure in the IDE) | |
-- if PORT is nil, the DBGP_IDEPORT env var is used. | |
-- if the env var is nil, the default value '10000' is used. | |
-- | |
-- IDEIDEKEY: a string which is used as session key | |
-- if IDEKEY is nil, the DBGP_IDEKEY env var is used. | |
-- if the env var is nil, the default value 'luaidekey' is used. | |
-- | |
-- TRANSPORT: (advanced optional parameter) the module name of which implement the transport interface used to do the connection with the server. | |
-- by default the debugger use an internal implementation based on luasocket, but if can not use it, you could implement or use another transport layer implementation. | |
-- if TRANSPORT is nil, the DBGP_TRANSPORT env var is used. | |
-- if the env var is nil, the default value 'debugger.transport.luasocket' is used : this is the default implementation based on luasocket. | |
-- | |
-- PLATFORM: (advanced optional parameter) 'unix' or 'win32' string which define the kind of platform on which the program to debug is executed. | |
-- by default the debugger will try to guess it and surely success, if for some reasons it fails you could help it by precise the execution platform. | |
-- if PLATFORM is nil, the DBGP_PLATFORM env var is used. | |
-- if the env var is nil, the debugger will try to guess it. | |
-- | |
-- WORKINGDIR: (advanced optional parameter) the working directory in which the program to debug is executed. | |
-- by default the debugger will try to guess it and surely success, if for some reasons it fails you could help it by precise the working directory. | |
-- if WORKINGDIR is nil, the DBGP_WORKINGDIR env var is used. | |
-- if the env var is nil, the debugger will try to guess it. | |
-- | |
-- NBRETRY: (advanced optional parameter) the number of connection retry at start up. | |
-- if NBRETRY is nil, the DBGP_NBRETRY env var is used. | |
-- if the env var is nil, the default value is 10. | |
-- | |
------------------------------------------------------------------------------- | |
-- Known Issues: | |
-- * Functions cannot be created using the debugger and then called in program because their environment is mapped directly to | |
-- a debugger internal structure which cannot be persisted (i.e. used outside of the debug_hook). | |
-- * The DLTK client implementation does not handle context for properties. As a workaround, the context is encoded into the | |
-- fullname attribute of each property and is used likewise in property_get commands. The syntax is "<context ID>|<full name>" | |
-- * Dynamic code (compiled with load or loadstring) is not handled (the debugger will step over it, like C code) | |
-- Design notes: | |
-- * The whole debugger state is kept in a (currently) unique session table in order to ease eventual adaptation to a multi-threaded | |
-- model, as DBGp needs one connection per thread. | |
-- * Full names of properties are base64 encoded because they can contain arbitrary data (spaces, escape characters, ...), this makes | |
-- command parsing munch easier and faster | |
-- * This debugger supports asynchronous commands: any command can be done at any time, but some of them (continuations) can lead to | |
-- inconsistent states. In addition, this have a quite big overhead (~66%), if performance is an issue, a custom command to disable | |
-- async mode could be done. | |
-- * All commands are implemented in table commands, see this comments on this table to additional details about commands implementation | |
-- * The environments in which are evaluated user code (property_* and eval commands, conditional breakpoints, ...) is a read/write | |
-- mapping of the local environment of a given stack level (can be accessed with variable names). See Context for additional details. | |
-- Context instantiation is pooled inside a debugging loop with ContextManager (each stack level is instantiated only once). | |
-- * Output redirection is done by redefining print and some values inside the io table. See "Output redirection handling" for details. | |
-- Todo list: | |
-- * Override I/O in init function instead of on module loading. | |
-- * Allow to break programatically (debugger.break()). | |
-- * Break-on-error feature (break if an error is thrown and there is no pcall in stack to handle it). | |
-- * Use new 5.2 facilities to provide informations about function (arguments names, vararg, ...) | |
-- * Allow to see ... content for vararg functions (5.2 only) | |
-- * Inspect LuaJIT C data (http://lua-users.org/lists/lua-l/2011-02/msg01012.html) |