Debugging (Civ5) - Revision history

DonQuich at 12:06, 25 September 2012

2012-09-25T12:06:31Z

← Older revision		Revision as of 12:06, 25 September 2012
Line 1:		Line 1:
	''This page is a part of the [[Civ5 Modding Tutorials]].''		''This page is a part of the [[Civ5 Modding Tutorials]].''

	== Checklist ==		= Checklist =
	* Did you correctly import to the [[VFS (Civ5)\|VFS]] the files that need to be?		* Did you correctly import to the [[VFS (Civ5)\|VFS]] the files that need to be?
	* Did you correctly set up the actions and content tab in your project?		* Did you correctly set up the actions and content tab in your project?
Line 7:		Line 7:


	== XML Debugging ==		= XML Debugging =
	[[File:SQLiteManager.png\|frame\|View of the snapshot using SQLiteManager]]		[[File:SQLiteManager.png\|frame\|View of the snapshot using SQLiteManager]]
	=== Checking the logs ===		=== Checking the logs ===
Line 22:		Line 22:


	== Lua Debugging ==		= Lua Debugging =
	=== Using the Firetuner console ===		=== Using the Firetuner console ===
	If you correctly set up your [[#Configuration]], Civ5 will send all the Lua output to the Firetuner (and also to the <code>Lua.log</code> file). This includes all the debugging output but also any error that may arise, with their calls stack traces.		If you correctly set up your [[#Configuration]], Civ5 will send all the Lua output to the Firetuner (and also to the <code>Lua.log</code> file). This includes all the debugging output but also any error that may arise, with their calls stack traces.
Line 141:		Line 141:


	== Troubleshooting ==		= Troubleshooting =
	The [[Civ5 Useful Programs]] page presents you a number of tools you can use to inspect or modify the game. This is especially useful if you want to quickly reproduce a bug or test something, or to understand what is happening.		The [[Civ5 Useful Programs]] page presents you a number of tools you can use to inspect or modify the game. This is especially useful if you want to quickly reproduce a bug or test something, or to understand what is happening.
	* Let's say your mod adds a tech but you do not see in the techs panel. There is a FireTuner panel you can use to see a flat list of all the techs in-game.		* Let's say your mod adds a tech but you do not see in the techs panel. There is a FireTuner panel you can use to see a flat list of all the techs in-game.
Line 148:		Line 148:


	== Configuration ==		= Configuration =
	Look for the following files under <code>My Documents/My Games/Sid Meiers' Civilization V</code> and open them in a text editor like the notepad (not in a word processor).		Look for the following files under <code>My Documents/My Games/Sid Meiers' Civilization V</code> and open them in a text editor like the notepad (not in a word processor).
	* '''config.ini'''		* '''config.ini'''

DonQuich at 12:05, 25 September 2012

2012-09-25T12:05:15Z

← Older revision		Revision as of 12:05, 25 September 2012
Line 58:		Line 58:


	The [[Lua introduction for confirmed developers]] describes a number of techniques you can use to achieve similar results. Here we present an implementation you can use to handle errors in the most dangerous parts of your code in order to present them to the user ~~with~~ a full stack trace when available.		The [[Lua introduction for confirmed developers]] describes a number of techniques you can use to achieve similar results. Here we present an implementation you can use to handle errors in the most dangerous parts of your code in order to present them to the user. The message will even include a full stack trace when available (you can provide your users a link to the [[#Configuration]] section and ask them to modify their config.ini).
	<div class="civ5-example"><syntaxhighlight lang="lua">		<div class="civ5-example"><syntaxhighlight lang="lua">
	-- Returns an array of strings, one for each call level.		-- Returns an array of strings, one for each call level.

DonQuich at 11:59, 25 September 2012

2012-09-25T11:59:28Z

← Older revision		Revision as of 11:59, 25 September 2012
Line 52:		Line 52:


	=== ~~Handling errors for the~~ end ~~user~~ ===		=== The end users' feedback ===
	Most of the time, when one of your user encounters an error with your mod, he just stops using it. A fraction of them will do the effort of reporting bugs but too often the informations they provide is unusable (from "it doesn't work" to wrong reproduction steps "play until turn 173 and wait for Mars being aligned with Venus"). The best way to increase the number of reports and their usefulness is to let your mod tell them the info it needs, as illustrated below.		Most of the time, when one of your user encounters an error with your mod, he just stops using it. A fraction of them will do the effort of reporting bugs but too often the informations they provide is unusable (from "it doesn't work" to wrong reproduction steps "play until turn 173 and wait for Mars being aligned with Venus"). The best way to increase the number of reports and their usefulness is to let your mod tell them the info it needs, as illustrated below.

DonQuich at 10:11, 25 September 2012

2012-09-25T10:11:32Z

← Older revision		Revision as of 10:11, 25 September 2012
Line 24:		Line 24:
	== Lua Debugging ==		== Lua Debugging ==
	=== Using the Firetuner console ===		=== Using the Firetuner console ===
	If you correctly set up your [[#Configuration]], Civ5 will send all the Lua output to the Firetuner. This includes all the debugging output but also any error that may arise, with their calls stack traces.		If you correctly set up your [[#Configuration]], Civ5 will send all the Lua output to the Firetuner (and also to the <code>Lua.log</code> file). This includes all the debugging output but also any error that may arise, with their calls stack traces.
	<pre>		<pre>
	Runtime Error: [string "C:\Users\Boss\Documents\My Games\Sid Meier'..."]:41: attempt to concatenate local 'name' (a nil value)		Runtime Error: [string "C:\Users\Boss\Documents\My Games\Sid Meier'..."]:41: attempt to concatenate local 'name' (a nil value)
Line 37:		Line 37:

	Note that paths are truncated in the provided example, which makes debugging harder sometimes. This happens when the file is in a {{Type5\|context}} registered by the project's ''content'' tab. Here are the workarounds:		Note that paths are truncated in the provided example, which makes debugging harder sometimes. This happens when the file is in a {{Type5\|context}} registered by the project's ''content'' tab. Here are the workarounds:
			* Provide a custom stack trace, as explained in a further section.
	* Register only a minimalist context, that will load additional contexts (through the UI LuaContext markup). Do not initiate any action from the root context, let the children context handle everything.		* Register only a minimalist context, that will load additional contexts (through the UI LuaContext markup). Do not initiate any action from the root context, let the children context handle everything.
	* ~~Provide a custom stack trace,~~ as ~~explained in~~ a ~~further section~~.		* Modifying your system paths is not recommended as it can cause incompatibilities with a few applications (old or badly written).

DonQuich at 10:10, 25 September 2012

2012-09-25T10:10:01Z

← Older revision		Revision as of 10:10, 25 September 2012
Line 150:		Line 150:
	Look for the following files under <code>My Documents/My Games/Sid Meiers' Civilization V</code> and open them in a text editor like the notepad (not in a word processor).		Look for the following files under <code>My Documents/My Games/Sid Meiers' Civilization V</code> and open them in a text editor like the notepad (not in a word processor).
	* '''config.ini'''		* '''config.ini'''
			** Set <code>EnableTuner</code> to 1. Civ5 will duplicate the Lua output to FireTuner this one is when present.
	** Set <code>LoggingEnabled</code> to 1. Civ5 will write log files under the <code>Logs</code> folder.		** Set <code>LoggingEnabled</code> to 1. Civ5 will write log files under the <code>Logs</code> folder.
	** Set <code>EnableLuaDebugLibrary</code> to 1. Civ5 will display stack traces on Lua errors and you will be able to use the [http://www.lua.org/manual/5.1/manual.html#pdf-debug.debug debug] object.		** Set <code>EnableLuaDebugLibrary</code> to 1. Civ5 will display stack traces on Lua errors and you will be able to use the [http://www.lua.org/manual/5.1/manual.html#pdf-debug.debug debug] object.

DonQuich at 14:02, 24 September 2012

2012-09-24T14:02:52Z

← Older revision		Revision as of 14:02, 24 September 2012
Line 59:		Line 59:
	The [[Lua introduction for confirmed developers]] describes a number of techniques you can use to achieve similar results. Here we present an implementation you can use to handle errors in the most dangerous parts of your code in order to present them to the user with a full stack trace when available.		The [[Lua introduction for confirmed developers]] describes a number of techniques you can use to achieve similar results. Here we present an implementation you can use to handle errors in the most dangerous parts of your code in order to present them to the user with a full stack trace when available.
	<div class="civ5-example"><syntaxhighlight lang="lua">		<div class="civ5-example"><syntaxhighlight lang="lua">
	-- Returns an array of strings, one for each call level.		-- Returns an array of strings, one for each call level.
			-- We could use debug.traceback instead but this ones truncates path and we cannot easily ignore the topmost levels.
	function getStackTrace()		function getStackTrace()
	-- Level 1 is getStackTrace, 2 is its caller		-- Level 1 is getStackTrace, 2 is its caller

DonQuich at 14:00, 24 September 2012

2012-09-24T14:00:38Z

← Older revision		Revision as of 14:00, 24 September 2012
Line 48:		Line 48:


	<code>assert('''variant''' condition, '''string''' message = "assertion failed")</code> can be used to assert the provided condition is neither nil nor false (everything else is evaluated to true in Lua). Otherwise, an error with the specified message is thrown. You can use them punctually, as a debugging technique. But they may also be used as a defensive programming technique ~~such as~~ [http://en.wikipedia.org/wiki/Design_by_contract design-by-contract]: the idea is that whenever your program's correctness relies on an assumption, you should explicitly check it. For example, if a function takes an array as an argument and assumes that it is not empty, you should add two conditions at the beginning: <code>assert(type(t) == "table")</code> and <code>assert(#t > 0)</code>. This makes the code more self-explanatory (implicit assumptions are now explicitly stated) and it allows you to catch bugs as soon as possible, which typically makes them easier to understand and fix.		<code>assert('''variant''' condition, '''string''' message = "assertion failed")</code> can be used to assert the provided condition is neither nil nor false (everything else is evaluated to true in Lua). Otherwise, an error with the specified message is thrown. You can use them punctually, as a debugging technique. But they may also be used as a defensive programming technique similar to [http://en.wikipedia.org/wiki/Design_by_contract design-by-contract]: the idea is that whenever your program's correctness relies on an assumption, you should explicitly check it. For example, if a function takes an array as an argument and assumes that it is not empty, you should add two conditions at the beginning: <code>assert(type(t) == "table")</code> and <code>assert(#t > 0)</code>. This makes the code more self-explanatory (implicit assumptions are now explicitly stated) and it allows you to catch bugs as soon as possible, which typically makes them easier to understand and fix.

DonQuich at 13:59, 24 September 2012

2012-09-24T13:59:53Z

← Older revision		Revision as of 13:59, 24 September 2012
Line 1:		Line 1:
	''This page is a part of the [[Civ5 Modding Tutorials]].''		''This page is a part of the [[Civ5 Modding Tutorials]].''

	~~'''This article is under construction, come back in a few days.'''~~

	== Checklist ==		== Checklist ==
Line 13:		Line 11:
	=== Checking the logs ===		=== Checking the logs ===
	If you correctly set up your [[#Configuration]], whenever you start a game, Civ5 saves some logs under <code>My Games/Sid Medier's Civilization V/cache/Civ5DebugDatabase.db</code>.		If you correctly set up your [[#Configuration]], whenever you start a game, Civ5 saves some logs under <code>My Games/Sid Medier's Civilization V/cache/Civ5DebugDatabase.db</code>.
	* If there were errors with the XML formatting of your data files (wrong column names for example), they will logged in XML.log.		* If there were errors with the XML formatting of your data files (wrong column names for example), they will logged in XML.log. Some of those errors may be fatal: in such a case no mod is loaded!
	:<pre>[6904.323] Tag (TXT_KEYMODDING_SHOWDLCMODS) does not start with 'TXT_KEY_'</pre>		:<pre>[6904.323] Tag (TXT_KEYMODDING_SHOWDLCMODS) does not start with 'TXT_KEY_'</pre>
	* If there were errors with the data integrity (missing foreign keys for example - types that reference rows from other tables), they will logged in database.log.		* If there were errors with the data integrity (missing foreign keys for example - types that reference rows from other tables), they will logged in database.log.

DonQuich at 13:55, 24 September 2012

2012-09-24T13:55:31Z

← Older revision		Revision as of 13:55, 24 September 2012
Line 94:		Line 94:
	levelsToIgnoreBelow = (levelsToIgnoreBelow or 0) + 1;		levelsToIgnoreBelow = (levelsToIgnoreBelow or 0) + 1;

	-- ~~We get an error~~ like: [string "C:\Users\Boss\Documents\My Games\Sid Meier'..."]:41: attempt to concatenate local 'name' (a nil value)		-- 'err' is like: [string "C:\Users\Boss\Documents\My Games\Sid Meier'..."]:41: attempt to concatenate local 'name' (a nil value)
	-- We retrieve important positions in this string. ~~Beware~~: not all paths are truncated		-- We retrieve important positions in this string. Remember: not all paths are truncated.
	local elipsisIndex = string.find(err, "...", 1, true) or -5;		local elipsisIndex = string.find(err, "...", 1, true) or -5;
	local lineIndex = elipsisIndex + 6		local lineIndex = elipsisIndex + 6
Line 112:		Line 112:
	end		end
	end		end
			-- Otherwise just report the line and message, and the source file when not truncated.
	else		else
	result = "line "..string.sub(err, elipsisIndex)		result = "line "..string.sub(err, elipsisIndex)
Line 127:		Line 128:
	err = formatError(err, 1);		err = formatError(err, 1);

	-- Show popup to user		-- Show a popup to the user
	local str = L("Oops, an error occured:").."[NEWLINE][ICON_PIRATE] "..err;		local str = L("Oops, an error occured:").."[NEWLINE][ICON_PIRATE] "..err;
	Events.SerialEventGameMessagePopup( { Type = ButtonPopupTypes.BUTTONPOPUP_TEXT, Data1 = 800, Option1 = true, Text = str } );		Events.SerialEventGameMessagePopup( { Type = ButtonPopupTypes.BUTTONPOPUP_TEXT, Data1 = 800, Option1 = true, Text = str } );

DonQuich at 13:52, 24 September 2012

2012-09-24T13:52:36Z

← Older revision		Revision as of 13:52, 24 September 2012
Line 56:		Line 56:
	Most of the time, when one of your user encounters an error with your mod, he just stops using it. A fraction of them will do the effort of reporting bugs but too often the informations they provide is unusable (from "it doesn't work" to wrong reproduction steps "play until turn 173 and wait for Mars being aligned with Venus"). The best way to increase the number of reports and their usefulness is to let your mod tell them the info it needs, as illustrated below.		Most of the time, when one of your user encounters an error with your mod, he just stops using it. A fraction of them will do the effort of reporting bugs but too often the informations they provide is unusable (from "it doesn't work" to wrong reproduction steps "play until turn 173 and wait for Mars being aligned with Venus"). The best way to increase the number of reports and their usefulness is to let your mod tell them the info it needs, as illustrated below.

	[[File:IGE-Error.png\|none\|frame\|[http://forums.civfanatics.com/showthread.php?t=436912 In-game editor] tells its users what they must report, even including a calls stack trace when available. The user only needs to make a screenshot that will then land on ~~their~~ Steam profile ~~with~~ the ~~default configuration~~. Reporting made easy!]]		[[File:IGE-Error.png\|none\|frame\|[http://forums.civfanatics.com/showthread.php?t=436912 In-game editor] tells its users what they must report, even including a calls stack trace when available. The user only needs to make a screenshot that will then land on his Steam profile (provided he didn't change the Steam settings). Reporting made easy!]]