Programming FAQ - Revision history

Mellinger at 09:43, 5 June 2023

2023-06-05T09:43:41Z

Mellinger: /* Debugging */

2013-01-17T20:07:14Z

Debugging

← Older revision		Revision as of 20:07, 17 January 2013
Line 74:		Line 74:
	*When using MSVC, use a different compiler with warnings enabled, and try to understand those (gcc/MinGW).		*When using MSVC, use a different compiler with warnings enabled, and try to understand those (gcc/MinGW).
	*Try out various optimization settings in the release build in order to identify the type of optimization that triggers the bug.		*Try out various optimization settings in the release build in order to identify the type of optimization that triggers the bug.

	~~----~~

	Q: My BCI2000 module crashed badly, and now each time I start BCI2000, I get a message as if the module were still running, and I cannot run BCI2000 any more. After restarting the machine, I can run BCI2000 again.

	A: BCI2000 modules use shared objects to indicate that they are currently running. When a module crashes badly, it will not be able to remove the object that indicates its presence. Thus, further attempts to start the module will fail. Running the module in question once with the <tt>--AllowMultipleInstances</tt> command line option will help. To generally avoid such situations, follow this advice:
	*When running a BCI2000 module under a debugger, specify <tt>--AllowMultipleInstances</tt> on the modules' command line.
	*Do not call the abort() C library function directly or indirectly in a BCI2000 module. Using of exit() is possible, but it is generally preferable to throw a descendant of BCIException (src/shared/bcistream/BCIException) in case of an unrecoverable error. This will allow the module to terminate in a graceful way, and to provide some error information to the user.

	----		----

Mellinger: /* Debugging */

2013-01-17T19:59:46Z

Debugging

← Older revision		Revision as of 19:59, 17 January 2013
Line 12:		Line 12:
	*If using Visual Studio, switch to debug mode, right-click the module's project, and choose "Rebuild" from the context menu.		*If using Visual Studio, switch to debug mode, right-click the module's project, and choose "Rebuild" from the context menu.
	*If building from the command line, re-run the appropriate shell script from the BCI2000/build folder, with <tt>-DCMAKE_BUILD_TYPE=Debug</tt> added as a command-line option, e.g.		*If building from the command line, re-run the appropriate shell script from the BCI2000/build folder, with <tt>-DCMAKE_BUILD_TYPE=Debug</tt> added as a command-line option, e.g.
	cd BCI2000/build		<nowiki>cd BCI2000/build
	./"Create Unix Makefiles.sh" -DCMAKE_BUILD_TYPE=Debug		./"Create Unix Makefiles.sh" -DCMAKE_BUILD_TYPE=Debug
	make MySignalProcessing</~~pre~~>		make MySignalProcessing</nowiki>
	#Add the # comment indicator in front of the module's startup command in the batch file you are using to start up BCI2000. If you are using BCI2000Launcher, adapt one of the batch files in BCI2000/batch to start up your desired configuration, and use that batch file during debugging.		#Add the # comment indicator in front of the module's startup command in the batch file you are using to start up BCI2000. If you are using BCI2000Launcher, adapt one of the batch files in BCI2000/batch to start up your desired configuration, and use that batch file during debugging.
	#Execute the batch file. This will start all required modules except the one you are debugging.		#Execute the batch file. This will start all required modules except the one you are debugging.

Mellinger: /* Debugging */

2013-01-17T19:55:01Z

Debugging

@@ Line 6: / Line 6: @@
 ==Debugging==
-Q: How do I debug a BCI2000 module?
+Q: How do I run a BCI2000 module from a debugger?
 A:
 #Add the # comment indicator in front of the module's startup command in the batch file you are using to start up BCI2000. If you are using BCI2000Launcher, adapt one of the batch files in BCI2000/batch to start up your desired configuration, and use that batch file during debugging.
-#Use your compiler to compile the module in debug mode.
+#Execute the batch file. This will start all required modules except the one you are debugging.
-#Execute the batch file.
+#Run the module in the debugging environment.
-#Change to the IDE, and run the module in the debugger.
+*Make sure to run the module with its working directory set to the BCI2000/prog folder, and all command line options (remaining text after the module name, on the same line in the batch file) are present when the module is run.
 ----
 Q: I keep getting "Unexpected system state transition 11->1" error messages from the operator module.

Mellinger: /* Debugging */

2012-06-13T14:32:28Z

Debugging

← Older revision		Revision as of 14:32, 13 June 2012
Line 9:		Line 9:

	A:		A:
	#Add the ~~"rem"~~ comment indicator in front of the module's startup command in the batch file you are using to start up BCI2000.		#Add the # comment indicator in front of the module's startup command in the batch file you are using to start up BCI2000. If you are using BCI2000Launcher, adapt one of the batch files in BCI2000/batch to start up your desired configuration, and use that batch file during debugging.
	~~#In~~ the ~~Borland IDE, go~~ to ~~"Project->Options->Compiler"~~, ~~click "Full Debug"~~ and ~~"OK", and recompile~~ the module.		#Use your compiler to compile the module in debug mode.
	#Execute the batch file.		#Execute the batch file.
	#Change to the IDE, and run the module in the debugger.		#Change to the IDE, and run the module in the debugger.

Mellinger: /* Getting Started with a new Module */

2011-04-20T13:39:29Z

Getting Started with a new Module

← Older revision		Revision as of 13:39, 20 April 2011
Line 47:		Line 47:
	Q: How should I begin working on a new BCI2000 module?		Q: How should I begin working on a new BCI2000 module?

	A: BCI2000 ~~modules share~~ a ~~large number of source files, and should have identical compiler settings. Thus, it is best~~ to ~~begin with a copy of an existing module's project, choosing the one that is most similar to your planned module~~. ~~Then, follow these steps:~~		A: BCI2000 provides a mechanism to create new BCI2000 modules from templates. To create a new BCI2000 module, run <tt>BCI2000/build/NewBCI2000Module</tt>; for a new filter, run <tt>BCI2000/build/NewBCI2000Filter</tt>. Both executables will only be present when you have built BCI2000 first as described [[Programming Reference:Build System\|here]].
	~~#Create~~ a new, ~~empty directory inside the appropriate~~ BCI2000/~~src~~/~~contrib~~/ ~~subdirectory, using a name that fits your new module.~~
	~~#Create an empty directory "obj" inside the newly created directory.~~
	~~#Copy the template project file (e.g., SignalGenerator.bpr), and the identically named cpp file (e.g., SignalGenerator.cpp) to the new project directory.~~
	~~#Rename the bpr and the cpp file to what you want to be the name of the executable.~~
	~~#Using a text editor, do a search-and-replace within the bpr and the cpp files, replacing all occurrences of the original name (e.g., "SignalGenerator") with the new name.~~
	~~#Create~~ a new ~~cpp file for the new filter or ADC component, or copy an existing one as a template.~~
	~~#Open the bpr file using the Borland IDE.~~
	~~#In the IDE, choose View->Project Manager to get a list of project files, and check whether your~~ filter ~~or ADC class cpp file is listed there; if not, add your new cpp file to the list.~~
	~~#Add any required .lib files or auxiliary cpp files to the list of project files.~~
	~~#Compile and link using the IDE. When this works, do a command-line "make clean && make prepare"~~, ~~open the file~~ <tt>~~src~~/~~makefiles~~</tt>~~, and remove the leading # character from your new project's entry~~. ~~Then, doing a "make all" should include your new project~~.

	==Writing Filter Components==		==Writing Filter Components==

Mellinger: /* Writing Filter Components */

2008-05-29T15:34:25Z

Writing Filter Components

← Older revision		Revision as of 15:34, 29 May 2008
Line 74:		Line 74:

	A: Make sure that your component is instantiated.		A: Make sure that your component is instantiated.
	*For source and application components, make sure that there is a line <tt>RegisterFilter( YourFilterClassName, Position );</tt> somewhere in its cpp file.		*For source and application components, make sure that there is a line <tt>RegisterFilter( YourFilterClassName, Position );</tt> somewhere in its cpp file (preferably at the top, following <tt>#include</tt> statements).
	*For signal processing filters, make sure that your filter is listed in the signal module's PipeDefinition.cpp as a statement <tt>Filter( YourFilterClassname, Position );</tt>		*For signal processing filters, make sure that your filter is listed in the signal module's PipeDefinition.cpp as a statement <tt>Filter( YourFilterClassname, Position );</tt>

	[[Category:Howto]][[Category:Development]]		[[Category:Howto]][[Category:Development]]

Mellinger: /* Debugging */

2008-05-29T15:32:26Z

Debugging

← Older revision		Revision as of 15:32, 29 May 2008
Line 9:		Line 9:

	A:		A:
	#~~Comment out~~ the module ~~from~~ the ~~startup~~ batch file you are using.		#Add the "rem" comment indicator in front of the module's startup command in the batch file you are using to start up BCI2000.
	#In the Borland IDE, go to "Project->Options->Compiler", ~~and~~ click "Full Debug".		#In the Borland IDE, go to "Project->Options->Compiler", click "Full Debug" and "OK", and recompile the module.
	#Execute the batch file.		#Execute the batch file.
	#Change to the IDE, and run the module in the debugger.		#Change to the IDE, and run the module in the debugger.

Mellinger: /* Getting Started with a new Module */

2008-05-21T13:58:06Z

Getting Started with a new Module

← Older revision		Revision as of 13:58, 21 May 2008
Line 57:		Line 57:
	#In the IDE, choose View->Project Manager to get a list of project files, and check whether your filter or ADC class cpp file is listed there; if not, add your new cpp file to the list.		#In the IDE, choose View->Project Manager to get a list of project files, and check whether your filter or ADC class cpp file is listed there; if not, add your new cpp file to the list.
	#Add any required .lib files or auxiliary cpp files to the list of project files.		#Add any required .lib files or auxiliary cpp files to the list of project files.
	#Compile and link using the IDE. When this works, do a command-line "make clean && make prepare", open the file <tt>src/.makefiles</tt>, and remove the leading # character from your new project's entry. Then, doing a "make all" should include your new project.		#Compile and link using the IDE. When this works, do a command-line "make clean && make prepare", open the file <tt>src/makefiles</tt>, and remove the leading # character from your new project's entry. Then, doing a "make all" should include your new project.

	==Writing Filter Components==		==Writing Filter Components==

Mellinger: /* Source Code Access */

2008-02-22T20:22:58Z

Source Code Access

← Older revision		Revision as of 20:22, 22 February 2008
Line 31:		Line 31:

	A:		A:
	*Make sure you are using the Wiki/SVN account information that was sent to you per e-mail,		*Make sure you are using the Wiki/SVN account information that was sent to you per e-mail, not the BBS account, which is different.
	not the BBS account, which is different.		*Make sure your SVN client knows how to do Digest Authentification. Some precompiled SVN versions for Mac OS X have been reported not to work (the Fink distribution should).
	*Make sure your SVN client knows how to do Digest Authentification. Some precompiled SVN versions
	for Mac OS X have been reported not to work (the Fink distribution should).
	*Avoid interference from firewalls by [[Programming Howto:SVN Client Setup\|using SSL rather than plain HTTP communication]].		*Avoid interference from firewalls by [[Programming Howto:SVN Client Setup\|using SSL rather than plain HTTP communication]].

← Older revision		Revision as of 09:43, 5 June 2023
Line 27:		Line 27:
	Q: How do I debug a crash in a BCI2000 module?		Q: How do I debug a crash in a BCI2000 module?

	A: If the crash occurs in an unmodified module coming with BCI2000, we would very much appreciate a bug report containing information about how to trigger it, preferably using parameter and batch files as coming with BCI2000, or with appropriate files attached to the bug report. Bugs may preferably be reported through the [~~http~~://{{SERVERNAME}}/tracproj trac ticket system] (use the "login" link on the top right, and log in with your BCI2000 user account, then create a bug ticket), but posting on the [~~http~~://{{SERVERNAME}}/phpbb/viewforum.php?f=8 "known issues" forum] is also fine. Actual crashes (i.e., issues that lead to termination of a module) will be fixed as soon as possible, which will usually take from a few days up to a couple of weeks.		A: If the crash occurs in an unmodified module coming with BCI2000, we would very much appreciate a bug report containing information about how to trigger it, preferably using parameter and batch files as coming with BCI2000, or with appropriate files attached to the bug report. Bugs may preferably be reported through the [https://{{SERVERNAME}}/tracproj trac ticket system] (use the "login" link on the top right, and log in with your BCI2000 user account, then create a bug ticket), but posting on the [https://{{SERVERNAME}}/phpbb/viewforum.php?f=8 "known issues" forum] is also fine. Actual crashes (i.e., issues that lead to termination of a module) will be fixed as soon as possible, which will usually take from a few days up to a couple of weeks.

	If the crash occurs in a module that has been modified by adding your own code, or by making changes to existing code, you should first try to reproduce it with an unmodified BCI2000 module that comes closest to your modified module. If the crash only happens in conjunction with your modifications, the following information may be helpful to you:		If the crash occurs in a module that has been modified by adding your own code, or by making changes to existing code, you should first try to reproduce it with an unmodified BCI2000 module that comes closest to your modified module. If the crash only happens in conjunction with your modifications, the following information may be helpful to you:
Line 48:		Line 48:
	*Walking up one more function in the call stack will show you the function in which the crash occurred. If it is a BCI2000 framework function that threw a bciexception, the previous code lines will probably tell you the reason. Otherwise, examination of the crashing line, and the values of the variables used on that line, will provide you with the immediate reason for the crash.		*Walking up one more function in the call stack will show you the function in which the crash occurred. If it is a BCI2000 framework function that threw a bciexception, the previous code lines will probably tell you the reason. Otherwise, examination of the crashing line, and the values of the variables used on that line, will provide you with the immediate reason for the crash.
	*Walking up the call stack until you hit a function written by yourself will provide you with the origin of the crash in your own code.		*Walking up the call stack until you hit a function written by yourself will provide you with the origin of the crash in your own code.
	*If your own code does not appear in the call stack, you may have hit a bug in the BCI2000 framework, or your own code may have gone astray in ways affecting the BCI2000 framework, e.g. by inadvertently overwriting some memory in use by the framework. If you think that you have found a bug in BCI2000, you may report it [~~http~~://{{SERVERNAME}}/tracproj/newticket here] (use the "login" link on the top right, and log in with your BCI2000 user account). Your bug report will be most helpful if you add a description how to trigger the bug in one of the modules coming with BCI2000, if necessary with a minimum amount of code added for demonstration purposes. Actually, determining the minimum amount of changes to an existing module in order to trigger a bug is part of the effort you will need to spend on the question whether it was caused by interference with your own code, or not.		*If your own code does not appear in the call stack, you may have hit a bug in the BCI2000 framework, or your own code may have gone astray in ways affecting the BCI2000 framework, e.g. by inadvertently overwriting some memory in use by the framework. If you think that you have found a bug in BCI2000, you may report it [https://{{SERVERNAME}}/tracproj/newticket here] (use the "login" link on the top right, and log in with your BCI2000 user account). Your bug report will be most helpful if you add a description how to trigger the bug in one of the modules coming with BCI2000, if necessary with a minimum amount of code added for demonstration purposes. Actually, determining the minimum amount of changes to an existing module in order to trigger a bug is part of the effort you will need to spend on the question whether it was caused by interference with your own code, or not.
	*Once you are done analyzing the module's current state, there is no more information to be gained about the cause of the crash. You may simply abort execution from the debugger.		*Once you are done analyzing the module's current state, there is no more information to be gained about the cause of the crash. You may simply abort execution from the debugger.
	*Alternatively, you may detach the debugger from the module, and press "Enter" in the module's message box, or terminal window. This will cause module termination in the same way as it happens for release builds.		*Alternatively, you may detach the debugger from the module, and press "Enter" in the module's message box, or terminal window. This will cause module termination in the same way as it happens for release builds.
Line 88:		Line 88:
	you quit BCI2000. Check for this in the Task Manager's process view, and kill the runaway module		you quit BCI2000. Check for this in the Task Manager's process view, and kill the runaway module
	from there before restarting BCI2000. Also, if the runaway module is part of the BCI2000 core		from there before restarting BCI2000. Also, if the runaway module is part of the BCI2000 core
	distribution, we will be glad if you drop us a note [~~http~~://{{SERVERNAME}}/phpbb on the BBS].		distribution, we will be glad if you drop us a note [https://{{SERVERNAME}}/phpbb on the BBS].

	==Source Code Access==		==Source Code Access==