AmiWest Lesson 1 - Revision history

Costel Mincea: Text replacement - "" to ""

2025-01-26T19:28:40Z

Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

Bill Borsari at 06:11, 22 August 2016

2016-08-22T06:11:49Z

← Older revision		Revision as of 06:11, 22 August 2016
Line 221:		Line 221:
	{		{
	BPTR wa_Lock; /* a lock descriptor */		BPTR wa_Lock; /* a lock descriptor */
	~~BYTE~~ * wa_Name; /* a string relative to that lock */		STRPTR * wa_Name; /* a string relative to that lock */
	};		};
	</syntaxhighlight>		</syntaxhighlight>

Steven Solie at 21:06, 13 May 2013

2013-05-13T21:06:31Z

← Older revision		Revision as of 21:06, 13 May 2013
Line 333:		Line 333:
	int32 StringLen = 2048;		int32 StringLen = 2048;
	// Alloc memory for pathname string		// Alloc memory for pathname string
	filename = (STRPTR) IExec->AllocVecTags(StringLen, ~~TAG_DONE~~);		filename = (STRPTR) IExec->AllocVecTags(StringLen, TAG_END);
	if (filename)		if (filename)
	{		{
Line 498:		Line 498:

	// Alloc memory for pathname string		// Alloc memory for pathname string
	filename = (STRPTR) IExec->AllocVecTags(MaxPathLen+MaxFileLen, ~~TAG_DONE~~);		filename = (STRPTR) IExec->AllocVecTags(MaxPathLen+MaxFileLen, TAG_END);

	// Alloc disk object pointer for icon information		// Alloc disk object pointer for icon information

Lyle Hazelwood: /* Configuring ReadArgs */ Added note about no spaces in template

2013-01-08T00:48:57Z

Configuring ReadArgs: Added note about no spaces in template

← Older revision		Revision as of 00:48, 8 January 2013
Line 117:		Line 117:
	CONST_STRPTR argTemplate = "TEST/K,NUMBER/K/N,FILE";		CONST_STRPTR argTemplate = "TEST/K,NUMBER/K/N,FILE";
	</syntaxhighlight>		</syntaxhighlight>
			[Note: Make sure there are no spaces in your template!]

	This template allows the user to enter the following optional settings for an application:		This template allows the user to enter the following optional settings for an application:

Steven Solie: /* Accessing the WBStartup structure */

2012-10-19T22:29:27Z

Accessing the WBStartup structure

← Older revision		Revision as of 22:29, 19 October 2012
Line 192:		Line 192:

	<syntaxhighlight>		<syntaxhighlight>
	if (argc = 0)		if (argc == 0)
	{		{
	struct WBStartup wbs = (struct WBStartup )argv;		struct WBStartup wbs = (struct WBStartup )argv;

Steven Solie: /* Using ReadArgs Results */

2012-10-19T22:22:13Z

Using ReadArgs Results

← Older revision		Revision as of 22:22, 19 October 2012
Line 144:		Line 144:

	====Using ReadArgs Results====		====Using ReadArgs Results====
	For example, with the above code, the first entry ('''argArray[0]''') would point to any valid input that followed the "~~TEXT~~" keyword, if it was in the command line. This value could be printed as follows:		For example, with the above code, the first entry ('''argArray[0]''') would point to any valid input that followed the "TEST" keyword, if it was in the command line. This value could be printed as follows:

	<syntaxhighlight>		<syntaxhighlight>
	if ((int32 *)argArray[0] != NULL)		if ((int32 *)argArray[0] != NULL)
	IDOS->Printf(" ~~TEXT~~ = %s\n", (STRPTR)argArray[0]);		IDOS->Printf(" TEST = %s\n", (STRPTR)argArray[0]);
	</syntaxhighlight>		</syntaxhighlight>

Steven Solie: /* Example Program Source Code */

2012-10-19T00:06:56Z

Example Program Source Code

← Older revision		Revision as of 00:06, 19 October 2012
Line 368:		Line 368:

	From the Workbench, this example will print out all the above information found on all the arguments passed by the Workbench. Besides the application's information, the printed information will reflected selected icons or Projects calling this app as a default Tool.		From the Workbench, this example will print out all the above information found on all the arguments passed by the Workbench. Besides the application's information, the printed information will reflected selected icons or Projects calling this app as a default Tool.

			An archive for use with CodeBench is available [[Media:ArgParser.lha\|from here]].

	<syntaxhighlight>		<syntaxhighlight>

Paul Sadlik: /* Program Startup */

2012-10-14T15:29:54Z

Program Startup

← Older revision		Revision as of 15:29, 14 October 2012
Line 46:		Line 46:
	== Program Startup ==		== Program Startup ==

	There are two primary environments in which a user can start applications in AmigaOS - by Shell console or by Workbench. Each method comes with ~~it's~~ own way of sending the application its starting arguments, data or options.		There are two primary environments in which a user can start applications in AmigaOS - by Shell console or by Workbench. Each method comes with its own way of sending the application its starting arguments, data or options.

	With the Workbench, the user can either double-click the application's icon, shift click the app and some other icon(s) or double-click an icon that has this application as its "default tool".		With the Workbench, the user can either double-click the application's icon, shift click the app and some other icon(s) or double-click an icon that has this application as its "default tool".
Line 90:		Line 90:
	=== Starting from the Console: the AmigaOS way ===		=== Starting from the Console: the AmigaOS way ===

	AmigaOS provides an alternate way for applications to parse arguments from a Shell command line using the '''ReadArgs''' function. In its most common use, this function will parse command line arguments according to a "template" defined by the application. If the user follows the command name with a question mark, this function will print the application's commands template and then allow the user type in their arguments. If the user fails to provide a valid command line, then '''ReadArgs''' lets the application know and the application can then exit gracefully.		AmigaOS provides an alternate way for applications to parse arguments from a Shell command line using the '''ReadArgs''' function. In its most common use, this function will parse command line arguments according to a "template" defined by the application. If the user follows the command name with a question mark, this function will print the application's commands template and then allow the user to type in their arguments. If the user fails to provide a valid command line, then '''ReadArgs''' lets the application know and the application can then exit gracefully.

	More information about this topic can be found in [[AmigaDOS_Programming#Standard_Command_Line_Parsing\|Standard Command Line Parsing]].		More information about this topic can be found in [[AmigaDOS_Programming#Standard_Command_Line_Parsing\|Standard Command Line Parsing]].
Line 112:		Line 112:
	:* '''/M''' - Multiple strings - indicates following strings except for keywords are settings		:* '''/M''' - Multiple strings - indicates following strings except for keywords are settings

	Here is an code example of how such a "template" definition could look like:		Examples of such templates can be found by typing most any AmigaOS command line command with a "?". Here is an code example of how such a "template" definition could look like:

	<syntaxhighlight>		<syntaxhighlight>
Line 144:		Line 144:

	====Using ReadArgs Results====		====Using ReadArgs Results====
	For example, with the above code, the first entry ('''argArray[0]''') would point to any valid input that followed "TEXT" keyword, if it was in the command line. This value could be printed as follows:		For example, with the above code, the first entry ('''argArray[0]''') would point to any valid input that followed the "TEXT" keyword, if it was in the command line. This value could be printed as follows:

	<syntaxhighlight>		<syntaxhighlight>
Line 177:		Line 177:

	:*'''The user double-clicked on the application's icon''' - In which case the '''WBStartup''' structure will indicate the program's name and "lock" its directory location on disk.		:*'''The user double-clicked on the application's icon''' - In which case the '''WBStartup''' structure will indicate the program's name and "lock" its directory location on disk.

	:*'''The user double-clicked on "project" file's icon that had this application set as its "tool"''' - In addition to the app's information, the '''WBStartup''' structure will indicate the project file's name and "lock" the project file's directory.		:*'''The user double-clicked on the "project" file's icon that had this application set as its "tool"''' - In addition to the app's information, the '''WBStartup''' structure will indicate the project file's name and "lock" the project file's directory.

	:*'''The user selected one (or more) "project" files and shift-double-clicked on the application's icon''' - The '''WBStartup''' structure will have a file name and directory "lock" for each of the project files in addition to the application's information.		:*'''The user selected one (or more) "project" files and shift-double-clicked on the application's icon''' - The '''WBStartup''' structure will have a file name and directory "lock" for each of the project files in addition to the application's information.

Line 187:		Line 189:
	==== Accessing the WBStartup structure ====		==== Accessing the WBStartup structure ====

	When started by the Workbench, an application is passed a pointer to the '''WBStartUp''' structure in the standard '''argv''' variable. After checking the '''argc''' variable is equal to zero (to see that we ~~were~~ started by the Workbench), the '''WBStartUp'' can be obtained like this:		When started by the Workbench, an application is passed a pointer to the '''WBStartUp''' structure in the standard '''argv''' variable. After checking the '''argc''' variable is equal to zero (to see that it was started by the Workbench), the '''WBStartUp'' structure can be obtained like this:

	<syntaxhighlight>		<syntaxhighlight>
Line 236:		Line 238:
	</syntaxhighlight>		</syntaxhighlight>

	Below we will see how to obtain more information from the selected files and how to get full path names for each. When the application finishes running, AmigaOS will release the "locks" on the directories referred to be the '''WBStartUp''' entries.		Below we will see how to obtain more information from the selected files and how to get full path names for each. When the application finishes running, AmigaOS will release the "locks" on the directories referred to by the '''WBStartUp''' entries.

	=== WorkBench StartUp: Examining Icons & Tooltypes ===		=== WorkBench StartUp: Examining Icons & Tooltypes ===
Line 249:		Line 251:
	These "Tool Type" settings are usually stored within the application's icon, but such settings can be also stored in most any icon files in AmigaOS. As such, an application can also look for such information within each project's icon file.		These "Tool Type" settings are usually stored within the application's icon, but such settings can be also stored in most any icon files in AmigaOS. As such, an application can also look for such information within each project's icon file.

	For an application to access any information that might be stored in its icon's '''.info''' file or in those of the "Projects" passed to the application, the application needs to go through a few more steps (after ~~those~~ above).		For an application to access any information that might be stored in its icon's '''.info''' file or in those of the "Projects" passed to the application, the application needs to go through a few more steps after collecting the related file names (mentioned above).

	More information about this topic can be found in [[Workbench_and_Icon_Library#The_Tool_Types_Array\|Tool Types Array]].		More information about this topic can be found in [[Workbench_and_Icon_Library#The_Tool_Types_Array\|Tool Types Array]].
Line 283:		Line 285:
	</syntaxhighlight>		</syntaxhighlight>

	The '''GetDiskObjectNew''' function automatically appends the ".info" necessary to open the selected file's icon. If there is no .info file for the selected file, this function will automatically use the information from "default icon" for the selected file type. For example, if the file "test.jpg" has no "test.jpg.info" icon file, the "def_jpeg.info" will be used.		The '''GetDiskObjectNew''' function automatically appends the ".info" necessary to open the selected file's icon. If there is no .info file for the selected file, this function will automatically use the information from the "default icon" for the selected file type. For example, if the file "test.jpg" has no "test.jpg.info" icon file, the "def_jpeg.info" will be used.

	If an application needs to explore icon information for a file not in the current directory of the app, the '''GetDiskObjectNew''' function will also accept the name of a file including a full path. But as we will see below, this does involve the application going through the overhead of allocating a string sufficient to store the full file & path name.		If an application needs to explore icon information for a file not in the current directory of the app, the '''GetDiskObjectNew''' function will also accept the name of a file including a full path. But as we will see below, this does involve the application going through the overhead of allocating a string sufficient to store the full file & path name.
Line 319:		Line 321:
	</syntaxhighlight>		</syntaxhighlight>

	With all the above code, an application can check each of the elements of the '''sm_ArgList''' sent by the Workbench to check ~~any application~~ Tool Types as well as any of the ~~Projects~~ sent to the app.		With all the above code, an application can check each of the elements of the '''sm_ArgList''' sent by the Workbench to check for Tool Types in the app's icon as well as any of the icons of any Project files sent to the app.

	=== Workbench StartUp: Getting Path & File Names ===		=== Workbench StartUp: Getting Path & File Names ===
Line 341:		Line 343:
	</syntaxhighlight>		</syntaxhighlight>

	As you can see, we allocate a large string size for the path name - 2048 characters - to provide room for potentially long and/or heavily nested path names. If that string is not long enough, the '''NameFromLock''' function will fail and return a NULL value. The developer ~~can~~ use their ~~judgement~~ in deciding how likely this error might be and how much effort to put into handling it - whether to have the application politely handle and notify the user of the error or whether to wrap this function in some loop that ~~kept~~ allocating larger string sizes until '''NameFromLock''' succeeds.		As you can see, we allocate a large string size for the path name - 2048 characters - to provide room for potentially long and/or heavily nested path names. If that string is not long enough, the '''NameFromLock''' function will fail and return a NULL value. The developer must use their judgment in deciding how likely this error might be and how much effort to put into handling it - whether to have the application politely handle and notify the user of the error or whether to wrap this function in some loop that keeps allocating larger string sizes until '''NameFromLock''' succeeds.

	Obviously, there are few levels of error trapping in this code: to make sure we were able to allocate our string ('''filename'''), to make sure there is a valid directory lock to use and finally to make sure the path name could be obtained from the lock. Regardless of how unlikely failure might be, within any application these tests should occur and be "wrapped" in proper and graceful error handling and feedback.		Obviously, there are few levels of error trapping in this code: to make sure we were able to allocate our string ('''filename'''), to make sure there is a valid directory lock to use and finally to make sure the path name could be obtained from the lock. Regardless of how unlikely failure might be, within any application these tests should occur and be "wrapped" in proper and graceful error handling and feedback.
Line 356:		Line 358:
	The resulting combined path and file name should be suitable for use by the application - to open or act upon the file selected by the user.		The resulting combined path and file name should be suitable for use by the application - to open or act upon the file selected by the user.

	Bear in mind, we are still working within the fixed size of the "filename" string, that must contain both the path name as well as the file name. ~~Like~~ before, we use a error trapping to check the combined file and path names fit into the string length we've defined. Again, should there be a failure, provide feedback and gracefully manage the situation.		Bear in mind, we are still working within the fixed size of the "filename" string that must contain both the path name as well as the file name. As before, we use error trapping to check that the combined file and path names fit into the string length we've defined. Again, should there be a failure, provide feedback and gracefully manage the situation.

	=== Example Program Source Code ===		=== Example Program Source Code ===

	The following is an example program to demonstrate the above concepts in starting an application from Shell and the Workbench.		The following is an example program to demonstrate the above concepts in starting an application from the Shell and the Workbench.

	From Shell, the user can enter arguments or enter the "?" to see the template prompt before entering arguments. Commented out within the code		From the Shell, the user can enter arguments or enter the "?" to see the template prompt before entering arguments. Commented out within the code
	is a working example of using the simple ANSI method of reading command line arguments.		is a working example of using the simple ANSI method of reading command line arguments.

Steven Solie: /* Standard C Library */

2012-10-03T01:08:48Z

Standard C Library

@@ Line 19: / Line 19: @@
  -mcrt=clib2 (non-thread safe version)
  -mcrt=clib2-ts (thread-safe version)
 == Program Startup ==

Steven Solie: /* Compiler, Linker and Libraries */

2012-10-03T00:27:09Z

Compiler, Linker and Libraries

← Older revision		Revision as of 00:27, 3 October 2012
Line 1:		Line 1:
	= AmiWest Lesson 1: Coding Basics =		= AmiWest Lesson 1: Coding Basics =

	== Compiler~~, Linker~~ and ~~Libraries~~ ==		== Compiler and Linker ==

	The [http://gcc.gnu.org/ GNU GCC toolset] is the officially supported standard compiler suite for Amiga operating system programming. An good alternative C compiler named [http://www.compilers.de/vbcc.html vbcc] is also supported and is popular with some programmers. We will focus on GCC which supports both C and C++.		The [http://gcc.gnu.org/ GNU GCC toolset] is the officially supported standard compiler suite for Amiga operating system programming. An good alternative C compiler named [http://www.compilers.de/vbcc.html vbcc] is also supported and is popular with some programmers. We will focus on GCC which supports both C and C++.
Line 8:		Line 8:

	There is a large wealth of detailed documentation and support for GNU GCC and programmers are encouraged to search around the internet. The Amiga-specific extensions are described on the [http://wiki.amigaos.net AmigaOS Documentation Wiki].		There is a large wealth of detailed documentation and support for GNU GCC and programmers are encouraged to search around the internet. The Amiga-specific extensions are described on the [http://wiki.amigaos.net AmigaOS Documentation Wiki].

			== Standard C Library ==

			AmigaOS officially uses a variant of the [http://sourceware.org/newlib/ Newlib C standard library] implementation. For programmers, it is essential to know what your C standard library is and what its limits are. Functions may or may not be available. Behaviour may or may not be identical between C standard library implementations.

			A popular alternative C standard library implementation is called [http://sourceforge.net/projects/clib2/ clib2] and it is included as an option with the standard Amiga SDK. The clib2 library is particular well suited for porting software from the Unix world. The complete source code for clib2 is also available which makes is possible to debug complex problems involving the C library itself.

			Switching between C standard library is easy thank to an Amiga-specific extension to GCC. The -mcrt option is used for both compiling and linking:
			-mcrt=newlib (default, always thread-safe)
			-mcrt=clib2 (non-thread safe version)
			-mcrt=clib2-ts (thread-safe version)

	== Program Startup ==		== Program Startup ==