====== INCBIN ======

Syntax:

  incbin "path/to/binary_file"

Or - in combination with ''[[DATA|DATA]]'':

  data varname![] = incbin "path/to/binary_file"

The ''INCBIN'' directive instructs the assembler to include a custom binary file. This is useful to include graphics, music or any kind of data - even machine code routines - in your program.

**Note**: the included file must be a path relative to the folder where the **XC=BASIC** source is.

**Important note**: if not using in combination with ''DATA'', you have to be very careful, as the binary stream will be "injected" into the program right at the point where the compiler encounters the directive. Make sure that the included data is outside the program flow (unless it's meant to be there).

An example of wrong usage:

	rem program starts here
	print "welcome to my buggy game"
	incbin "sprites.bin"
	print "now let's play"
	
In the example above, after printing the welcome message, the program will try to execute whatever is in "sprites.bin" which will likely result in a crash. The good practice is to separate your code and data or use a ''GOTO'' command to skip unwanted parts of the program.

The above example fixed:

	rem program starts here
	goto start
	incbin "sprites.bin"
	start:
		print "welcome to my cool game"
		print "now let's play"
		
Or:

	rem program starts here
	print "welcome to my cool game"
	print "now let's play"
	end
	incbin "sprites.bin"
		
Although the compiler will let you know the exact addresses where the included files got assembled within the final executable, these addresses may be changing. In most cases you will want to use ''INCBIN'' in combination with ''ORIGIN''  to make sure that your included binaries are always located at the same address. Another safe and useful usage is in combination with the ''DATA'' statement.