Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

add documentation at begin of debugger.lua file

  • Loading branch information...
commit c79b6e3d170f6a3ae00fc0675b575508764e187d 1 parent 75f27d0
@sbernard31 sbernard31 authored
View
22 libraries/luadbgpclient/build.xml
@@ -12,11 +12,11 @@
<project name="debuggerBuilder" default="build">
<!-- Calculate the folder which contains this current ant file-->
- <dirname property="antFileFolder" file="${ant.file}" />
-
+ <dirname property="antFileFolder" file="${ant.file}" />
+
<!--Output file name -->
<property name="debuggerFile" value="./debugger.lua" />
-
+
<!--Some constant string part of the generated file -->
<property name="header">-- /!\ This file is auto-generated. Do not alter manually /!\
@@ -32,8 +32,9 @@ package.preload["</property>
</property>
<property name="modulefooterstart">
end
+--------------------------------------------------------------------------------
-- End of module</property>
-<property name="modulefooterend">
+ <property name="modulefooterend">
--------------------------------------------------------------------------------
</property>
@@ -49,9 +50,12 @@ end
<delete file="${debuggerFile}" />
<touch file="${debuggerFile}" />
+ <loadfile property="documentation" srcFile="${antFileFolder}/debugger/readme.txt" />
+ <echo file="${debuggerFile}" append="true" message="${documentation}" />
+
<echo file="${debuggerFile}" append="true" message="${header}" />
</target>
-
+
<!--Find a path from a lua module name -->
<target name="findPath">
<script language="javascript">
@@ -59,11 +63,11 @@ end
project.setProperty("path", module.replace(".", "/") + ".lua");
</script>
</target>
-
+
<!--Append a module in the file -->
<target name="appendModule" depends="findPath">
<antcall target="findPath" />
-
+
<loadfile property="fileContent" srcFile="${antFileFolder}/${path}" />
<echo file="${debuggerFile}" append="true" message="${moduleheaderstart}${module}" />
<echo file="${debuggerFile}" append="true" message="${moduleheadermidle}${module}" />
@@ -76,7 +80,7 @@ end
<!--Append the main in the file -->
<target name="appendMain" depends="findPath">
<antcall target="findPath" />
-
+
<loadfile property="fileContent" srcFile="${antFileFolder}/${path}" />
<echo file="${debuggerFile}" append="true" message="${mainheader}" />
<echo file="${debuggerFile}" append="true" message="${fileContent}" />
@@ -95,7 +99,7 @@ end
<param name="module" value="debugger.transport.luasocket" />
</antcall>
<antcall target="appendModule">
- <param name="module" value="debugger.transport.luasocket_sched" />
+ <param name="module" value="debugger.transport.luasocket_sched" />
</antcall>
<antcall target="appendModule">
<param name="module" value="debugger.commands" />
View
58 libraries/luadbgpclient/debugger/init.lua
@@ -8,64 +8,6 @@
-- Contributors:
-- Sierra Wireless - initial API and implementation
-------------------------------------------------------------------------------
--- Debugger using DBGp protocol.
--------------------------------------------------------------------------------
--- The module returns a single init function which takes 6 parameters (IDEHOST, IDEPORT, IDEKEY, TRANSPORT, PLATFORM, WORKINGDIR).
---
--- 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.
---
--------------------------------------------------------------------------------
--- 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)
local debug = require "debug"
View
68 libraries/luadbgpclient/debugger/readme.txt
@@ -0,0 +1,68 @@
+-------------------------------------------------------------------------------
+-- 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 6 parameters (IDEHOST, IDEPORT, IDEKEY, TRANSPORT, PLATFORM, WORKINGDIR).
+--
+-- 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.
+--
+-------------------------------------------------------------------------------
+-- 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)
Please sign in to comment.
Something went wrong with that request. Please try again.