Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
reswrap(1)		    FOX	Programmers Manual		    reswrap(1)

NAME
       reswrap - wrap icon and image resources into C or C++ code

SYNOPSIS
       reswrap [options] [-o[a]	outfile] files...

DESCRIPTION
       Reswrap is a tool to turn binary	files into C or	C++ data arrays.  This
       allows various resources	such as	icons, images, or other	data to	be em-
       bedded  into source code	and compiled into an application. When used in
       text mode, normal printing characters are passed	normally while control
       characters or non-ascii are automatically escaped.

       In  development	of graphical applications with FOX, it is customary to
       embed icons, images, online help, or OpenGL  fragment  shader  programs
       into  the  executable  file,  thus removing the need to distribute such
       files separately	with the application.

       Reswrap is typically invoked as a part of the application build process
       to  generate additional C++ source files	from collections of icons, im-
       ages, or	other binary resources.	This can be easily accomplished	 using
       a  special  Makefile  Rule  or Custom Build Rule, as part of the	normal
       compile process of an application.  Reswrap supports a variety  of  op-
       tions to	facilitate inclusion into an automated build process.  Given a
       list of resource	files, reswrap can automatically generate header files
       containing  just	 the  declarations,  adorn  the	generated symbols with
       namespaces, prefixes and/or postfixes, file-extensions, and  apply  ex-
       tern  or	 static	linkage	attributes.  Resource filenames	containing un-
       safe characters are automatically transformed into legal	C or C++ iden-
       tifiers.

       By  default  reswrap will interpret the files listed as a stream	of raw
       bytes and output	them as	an initialized data array to stdout.

OPTIONS
       -?, --help
	      Print summary usage information of all the supported options.

       -v, --version
	      Print the	version	number and license information.

       -h, --header
	      Generate an output file containing  only	declarations  suitable
	      for including as a header	file.  This also enables the  --extern
	      option automatically.

       -s, --source
	      Generate an output file containing  data	arrays.	  This	option
	      disables	the  --extern option.  This option is the default when
	      no directives are	given.

       -V, --verbose
	      Print a list of the filenames, and  the  corresponding  resource
	      declarations generated as	reswrap	processes the resource files.

       -i file,	--include file
	      Generate a #include "file" directive in the output file, to make
	      the declarations available when compiling	the data source	file.

       -o file,	--output file
	      Write the	output of the conversion into file instead of  writing
	      to stdout.

       -oa file, --append file
	      Append  the  output of the conversion to file instead of writing
	      to stdout.  If  file does	not exist yet, it is created, and  the
	      optional	comment	line will be written, followed by the optional
	      #include "file" directive.  If the file already exists  then  it
	      will be opened for appending.

       -e, --extern
	      Places  the  storage modifier extern in front of the data	array,
	      ensuring that the	data array can be linked with  other  compila-
	      tion  units.  Normally, constant declarations are	not visible in
	      other compilation	units.	This option is automatically turned on
	      when --header is passed.

       -S, --static
	      Places  the  storage modifier static in front of the data	array.
	      This makes the symbols invisible outside the compilation unit.

       -z, --size
	      Output the size of the resource in  the  declaration  of	a  re-
	      source-array.   This  allows the sizeof()	operator to return the
	      correct size of the resource  even  for  external	 declarations.
	      Note  that  in  text mode, (--text or --ascii options), an extra
	      byte is added to the size	for the	end of string character.

       -d, --decimal
	      Write data as decimal numbers instead of using the default hexa-
	      decimal numbers.

       -x, --hex
	      Write data as hexadecimal	numbers. This option is	the default.

       -t, --text
	      Write  data  as  a  text string, with each byte represented as a
	      hexadecimal excape sequence, as in "\x33".  The C++ compiler ap-
	      pends a nul-character at the end of the text string, thus	making
	      the data array one character longer than the resource file.

       -a, --ascii
	      Write data as a text string, with	each byte printed normally un-
	      less  it	must be	escaped, as in "\x33".	Use this option	if you
	      need to embed large chunks of text (for example,	on-line	 help)
	      into the application.  This lets you keep	the original text in a
	      plain text file, and obviates the	need to	manually  escape  spe-
	      cial  characters	to  embed them into source code.  The C++ com-
	      piler appends a nul-character at the end	of  the	 text  string,
	      thus  making  the	 data  array one character longer than the re-
	      source file.

	      With the --ascii option, printable ascii characters  are	passed
	      unescaped,  while	 special characters like tabs and newlines are
	      given the	usual escape codes.

       -k, --keep-ext
	      This option causes reswrap to keep the file extension, replacing
	      the  "."	with an	underscore "_".	 For example, image.gif	gener-
	      ates const unsigned char image_gif[].

	      This option is recommended as it reduces errors when  using  the
	      data arrays.

       -nk, --drop-ext
	      This option causes the declaration to be based only on the base-
	      name of the resource file.   For	example,  image.gif  generates
	      const unsigned char image[].

       -m, --msdos
	      Read  files  with	 MS-DOS	 mode.	This replaces "\r\n" with "\n"
	      when reading the resource	file.  Only use	this if	 the  resource
	      is actually text!

       -b, --binary
	      Read files in BINARY mode. Data other than text should always be
	      read in using binary mode.  This option is the default.

       -u, --unsigned
	      Generate unsigned	char declaration, even when  --text or --ascii
	      was specified.

       -N, --no-const
	      Do not generate const declarations.

       -C, --const
	      Force generation of const	declarations.

       -cc, --comments
	      Add  comments  to	the output files.  This	option is the default.
	      At the top of each output	file, write the	current	date, and  the
	      reswrap version number.

       -nc, --no-comments
	      Suppress generations of comments in the output files.

       -p name,	--prefix name
	      Prepend  the  given prefix in front of the name of the resource;
	      this may be used to generate class names or namespace  names  in
	      front of symbols.

       -f name,	--suffix name
	      Prepend  the  given prefix in front of the name of the resource;
	      this may be used to generate class names or namespace  names  in
	      front of symbols.

       -n name,	--namespace name
	      Generate	all declarations inside	the given C++ namespace	decla-
	      ration.  Using a namespace may be	used to	ensure	that  declara-
	      tions are	only accessible	within the given scope,	and thus won't
	      clash with symbols.

       -c cols,	--columns cols
	      Writes cols columns instead of the default number	of columns  in
	      the data statements generated by reswrap.	 The default number of
	      columns for decimal is 10	columns, while the default  for	 hexa-
	      decimal  printout	 is 16 columns.	 For text string printout, the
	      default is 80 characters.	 When the number of columns is set  to
	      0,  decimal  or  hexadecimal  output is printed without breaking
	      columns, while text output lines are broken  only	 at  the  new-
	      lines.

       -r name,	--resource name
	      Instead  of using	a resource name	based on the filename, reswrap
	      substitutes name for the resource	name used in  the  declaration
	      or  definition  for the following	resource file.	This is	useful
	      if the filename can not be used as an identifier,	for example if
	      the  filename  happens  to  be a reserved	word in	C or C++, like
	      "while.gif".

CAVEATS
       When using the text string mode,	please remember	the C compiler appends
       one  nul-character  after the string, making the	data array one element
       longer than the resource	file.

AUTHOR
       This manpage was	originally written by Torsten Landschoff  (torsten@de-
       bian.org)  for  the Debian distribution of the FOX Toolkit, and is cur-
       rently maintained by Jeroen van der Zijp	(jeroen@fox-toolkit.com).

COPYRIGHT
       Copyright (C) 1997,2016 Jeroen van der Zijp.
       This is free software; see the source for copying conditions.  There is
       NO warranty; not	even for MERCHANTABILITY or FITNESS FOR	 A  PARTICULAR
       PURPOSE.

SEE ALSO
       The reswrap program is a	part of	the FOX	GUI Toolkit.  Further informa-
       tion about reswrap can be found at:

       http://www.fox-toolkit.org

       The FOX Toolkit website includes	detailed information about reswrap and
       its use.

The FOX	C++ GUI	Toolkit		 January 2016			    reswrap(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | CAVEATS | AUTHOR | COPYRIGHT | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=reswrap-17&sektion=1&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help