S2scompile: Difference between revisions
Jump to navigation
Jump to search
No edit summary |
|||
| (52 intermediate revisions by 5 users not shown) | |||
| Line 1: | Line 1: | ||
__FORCETOC__ | |||
== The SCL Compiler Utility == | == The SCL Compiler Utility == | ||
The ''' | The '''s2scompile''' executable will compile a set of scl files (C/C++ source files with [[SCL Pragmas]]) and produce a <tt>.meta</tt> file for each (assuming that compilation is successful).<ref>.meta files are binary-format intermediate files suitable for input to the [[s2sbind]] utility.</ref> | ||
All warnings and errors that occur during the compilation are written to the standard output device. The compilation for a particular file is considered successful if no errors occur. Otherwise it is unsuccessful. Unsuccessful compilations do not yield <tt>.meta</tt> files. | |||
Options are validated and any incorrect options diagnosed will result in compilation process failure. | Options are validated and any incorrect options diagnosed will result in compilation process failure. | ||
=== Syntax === | === Syntax === | ||
s2scompile [<i>options</i>] <i>scl_file1</i> [<i>scl_fileN</i>] | s2scompile [<i>options</i>] <i>scl_file1</i> [<i>scl_fileN</i>] | ||
=== Options === | === Options === | ||
| Line 12: | Line 16: | ||
!width="500pt"|'''Description''' | !width="500pt"|'''Description''' | ||
|- | |- | ||
| -- | | '''--version''' | ||
| | | Print version information. | ||
|- | |- | ||
| --dependencies | | '''--preprocess''' | ||
| Do preprocessing only. Instead of the normal preprocessing output, generate in the preprocessing output file a list of dependency lines suitable for input to the UNIX make program. | | Do preprocessing only. Write preprocessed text file to the output. | ||
|- | |||
| '''--dependencies''' | |||
| Do preprocessing only. Instead of the normal preprocessing output, generate in the preprocessing output file a list of dependency lines suitable for input to the UNIX make program. | |||
|- | |- | ||
| --no_line_commands | | '''--no_line_commands''' | ||
| Same as '''–-preprocess''' except that line number information is removed from the preprocessed output files. | | Same as '''–-preprocess''' except that line number information is removed from the preprocessed output files. | ||
|- | |- | ||
| --c++ | | '''--c++''' | ||
| Enable compilation of c++. | | Enable compilation of c++. | ||
|- | |- | ||
| --c | | '''--c''' | ||
| Enable compilation of C (specifically C89). This is the default. | | Enable compilation of C (specifically C89). This is the default. | ||
|- | |- | ||
| --include_directory=<dir><br> | | '''--include_directory='''<i><dir></i><br> | ||
--sys_include=<i><dir></i><br> | '''--sys_include='''<i><dir></i><br> | ||
-I<i><dir></i> | '''-I'''<i><dir></i> | ||
| Add dir to the end of the list of directories searched for # | | Add dir to the end of the list of directories searched for <tt>#include</tt>. | ||
|- | |||
| '''--no_stdinc''' | |||
| Do not search the standard system directories for header files. See [[#Search Path|Search Path]] for details. | |||
|- | |||
| '''--define_macro='''<i><name></i>['''('''<i>parameter-list</i>''')''']['''='''<i>value</i>]<br> | |||
'''-D'''<i><name></i>['''('''<i>parameter-list</i>''')''']['''='''<i>value</i>] | |||
| Define macro <i><name></i> as <i>value</i>. If "=<i>value</i>" is omitted, define <i><name></i> as 1. | |||
|- | |- | ||
| -- | | '''--undefine_macro='''<i><name></i><br> | ||
'''-U'''<i><name></i> | |||
| | | Remove predefined macro <i><name></i>. | ||
|- | |||
| '''--preinclude='''<i><file></i> | |||
| Include file at the beginning of compilation. | |||
'''''NOTE:''' To simplify the integration in existing build environments other standard compiler options (e.g. GCC [https://gcc.gnu.org/onlinedocs/gcc/Preprocessor-Options.html -include<file>], MSVC [https://docs.microsoft.com/en-us/cpp/build/reference/fi-name-forced-include-file /FI@<file>]) with similar meaning are also recognized and processed the same way.'' | |||
|- | |- | ||
| -- | | '''--compatibility='''<i><string></i> | ||
| | | Vendor compatibility mode. String can be "microsoft", "generic" or "gnu". Default is "generic". When "Microsoft" is set, the compiler supports a number of extensions to the C or C++ language that are compatible with the Microsoft family of compilers. "gnu" - instructs the compiler to support language extensions compatible with the Gnu family of compilers. | ||
|- | |- | ||
| --no_warning | | '''--no_warning''' | ||
| Suppress all warnings in the compilation phase. | | Suppress all warnings in the compilation phase. | ||
|- | |- | ||
| -- | | '''--macros''' | ||
| | | Resolve macro (preprocessor define) constant value. Pass this flag only if you intend to do script based testing. | ||
|- | |||
| '''--documentation''' | |||
| Extract [https://en.wikipedia.org/wiki/Doxygen doxygen style] source documentation. | |||
|- | |- | ||
| --output=<i><path></i><br> | | '''--output='''<i><path></i><br> | ||
-o<path> | '''-o'''<path> | ||
| Output file or directory. The default is the current directory. | | Output file or directory. The default is the current directory. | ||
|- | |- | ||
| --targ_big_endian | | '''--targ_big_endian''' | ||
| Target uses a big endian by representation. The default is little endian. | | Target uses a big endian by representation. The default is little endian. | ||
|- | |- | ||
| --targ_plain_char_is_unsigned | | '''--targ_plain_char_is_unsigned''' | ||
| Target uses unsigned chars to represent “plain” char. The default is signed. | | Target uses unsigned chars to represent “plain” char. The default is signed. | ||
|- | |- | ||
| --targ_adaptive_enum | | '''--targ_adaptive_enum''' | ||
| Target has adaptive enums. The default is no adaptive enums. | | Target has adaptive enums. The default is no adaptive enums. | ||
|- | |- | ||
| --targ_pack_alignment=<i><align></i> | | '''--targ_pack_alignment='''<i><align></i> | ||
| Target struct pack alignment. The default is 16. Possible values are 1, 2, 4, 8 or 16. | | Target struct pack alignment. The default is 16. Possible values are 1, 2, 4, 8 or 16. | ||
|- | |- | ||
| --targ_sizeof_char=<i><size></i> | | '''--targ_sizeof_char='''<i><size></i> | ||
| Target platform size of char. Default is 1. Possible values are 1, 2, 4, 8, or 16. | | Target platform size of char. Default is 1. Possible values are 1, 2, 4, 8, or 16. | ||
|- | |- | ||
| --targ_alignof_char=<i><align></i> | | '''--targ_alignof_char='''<i><align></i> | ||
| Target platform alignment of char. Default is 1. Possible values are 1, 2, 4, 8 or 16. | | Target platform alignment of char. Default is 1. Possible values are 1, 2, 4, 8 or 16. | ||
|- | |- | ||
| --targ_sizeof_short=<i><size></i> | | '''--targ_sizeof_short='''<i><size></i> | ||
| Default is 2. | | Default is 2. | ||
|- | |- | ||
| --targ_alignof_short=<i><align></i> | | '''--targ_alignof_short='''<i><align></i> | ||
| Default is 2. | | Default is 2. | ||
|- | |- | ||
| --targ_sizeof_int=<i><size></i> | | '''--targ_sizeof_int='''<i><size></i> | ||
| Default is 4. | | Default is 4. | ||
|- | |- | ||
| --targ_alignof_int=<i><align></i> | | '''--targ_alignof_int='''<i><align></i> | ||
| Default is 4. | | Default is 4. | ||
|- | |- | ||
| --targ_sizeof_long=<i><size></i> | | '''--targ_sizeof_long='''<i><size></i> | ||
| Default is 4. | | Default is 4. | ||
|- | |- | ||
| --targ_alignof_long=<i><align></i> | | '''--targ_alignof_long='''<i><align></i> | ||
| Default is 4. | | Default is 4. | ||
|- | |- | ||
| --targ_sizeof_long_long=<i><size></i> | | '''--targ_sizeof_long_long='''<i><size></i> | ||
| Default is 8. | | Default is 8. | ||
|- | |- | ||
| --targ_alignof_long_long=<i><align></i> | | '''--targ_alignof_long_long='''<i><align></i> | ||
| Default is 8. | | Default is 8. | ||
|- | |- | ||
| --targ_sizeof_float=<i><size></i> | | '''--targ_sizeof_float='''<i><size></i> | ||
| Default is 4. | | Default is 4. | ||
|- | |- | ||
| --targ_alignof_float=<i><align></i> | | '''--targ_alignof_float='''<i><align></i> | ||
| Default is 4. | | Default is 4. | ||
|- | |- | ||
| --targ_sizeof_double=<i><size></i> | | '''--targ_sizeof_double='''<i><size></i> | ||
| Default is 8. | | Default is 8. | ||
|- | |- | ||
| --targ_alignof_double=<i><align></i> | | '''--targ_alignof_double='''<i><align></i> | ||
| Default is 8. | | Default is 8. | ||
|- | |- | ||
| --targ_sizeof_long_double=<i><size></i> | | '''--targ_sizeof_long_double='''<i><size></i> | ||
| Default is 8 | | Default is 8 | ||
|- | |- | ||
| --targ_alignof_long_double=<i><align></i> | | '''--targ_alignof_long_double='''<i><align></i> | ||
| Default is 8. | | Default is 8. | ||
|- | |- | ||
| --options_file=<i><file></i> | | '''--targ_bool_int_kind='''<i><typename></i> | ||
| A file that contains command line options. | | Default is "char". | ||
|- | |||
| '''--targ_wchar_t_int_kind='''<i><typename></i> | |||
| Default is "unsigned short". | |||
|- | |||
| '''--targ_size_t_int_kind='''<i><typename></i> | |||
| Default is "unsigned int". | |||
|- | |||
| '''--targ_ptrdiff_t_int_kind='''<i><typename></i> | |||
| Default is "int". | |||
|- | |||
| '''--options_file='''<i><file></i> | |||
| A file that contains command line options. The format is the same as the command line with the only addition that it could be split on multiple lines. A line starting with "#" or ";" symbol is ignored. | |||
This option is necessary if the length of the command line string exceeds system limits. Otherwise it is provided only as a convenience. | |||
'''''NOTE:''' To simplify the integration in existing build environments other standard compiler options (e.g. ARM [https://www.keil.com/support/man/docs/armcc/armcc_chr1359124949735.htm --via=<file>], GCC [https://gcc.gnu.org/onlinedocs/gcc/Overall-Options.html @<file>], MSVC [https://docs.microsoft.com/en-us/cpp/build/reference/at-specify-a-compiler-response-file @<file>]) with similar meaning are also recognized and processed the same way.'' | |||
|} | |} | ||
'''Note''': The [[Framework_Setup#SDK|standard Platform SDKs]] shipped with the Framework contain a set of options files with predefined target settings for several popular CPUs. Please consider using one of them instead of explicitly passing <tt>--targ_*</tt> options on the command line. | |||
=== Search Path === | |||
<b>s2scompile</b> by default looks in several different places for headers. It looks for headers requested with <tt>#include <file></tt> in: | |||
<pre> | |||
$(STRIDE_DIR)/SDK/Runtime | |||
</pre> | |||
Where $(STRIDE_DIR) is the location where the STRIDE packages are installed following [[Framework_Setup#Directories_and_Files|recommended directory layout]]. | |||
When <i>microsoft</i> mode is specified and $(INCLUDE) enviroment variable is defined (as a ";" separated path list) then all of its entries are looked in for headers requested with <tt>#include <file></tt>. | |||
When <i>gnu</i> mode is specified and $(CPATH) and/or $(C_INCLUDE_PATH) (or $(CPLUS_INCLUDE_PATH) for C++) enviroment variables are defined (as a ":" separated path list) then all of its entries are looked in for headers requested with <tt>#include <file></tt>. In addition if $(TARGET_CPP) specifies the target GNU <tt>cpp</tt> (GCC preprocessor or a command line equivalent) it is queried and any given path by it is looked in. | |||
You can add to this list, before any of the default places, by using the <tt>-I<dir></tt> option. | |||
You can prevent s2scompile from searching any of the default directories with the <tt>--no_stdinc</tt> option. <tt>-I</tt> options are not ignored as described above when <tt>--no_stdinc</tt> is in effect. | |||
<b>s2scompile</b> looks for headers requested with <tt>#include "file"</tt> first in the directory containing the current file, then in the same places it would have looked for a header requested with angle brackets. | |||
=== Examples === | |||
Refer to the [[Build_Tools#Compiling_multiple_files|Compiling]] section of the Build Tools Examples. | |||
=== Notes === | |||
<references/> | |||
[[Category:Build_Tools]] | |||
Latest revision as of 18:19, 6 August 2020
The SCL Compiler Utility
The s2scompile executable will compile a set of scl files (C/C++ source files with SCL Pragmas) and produce a .meta file for each (assuming that compilation is successful).[1]
All warnings and errors that occur during the compilation are written to the standard output device. The compilation for a particular file is considered successful if no errors occur. Otherwise it is unsuccessful. Unsuccessful compilations do not yield .meta files.
Options are validated and any incorrect options diagnosed will result in compilation process failure.
Syntax
s2scompile [options] scl_file1 [scl_fileN]
Options
| Option | Description |
|---|---|
| --version | Print version information. |
| --preprocess | Do preprocessing only. Write preprocessed text file to the output. |
| --dependencies | Do preprocessing only. Instead of the normal preprocessing output, generate in the preprocessing output file a list of dependency lines suitable for input to the UNIX make program. |
| --no_line_commands | Same as –-preprocess except that line number information is removed from the preprocessed output files. |
| --c++ | Enable compilation of c++. |
| --c | Enable compilation of C (specifically C89). This is the default. |
| --include_directory=<dir> --sys_include=<dir> |
Add dir to the end of the list of directories searched for #include. |
| --no_stdinc | Do not search the standard system directories for header files. See Search Path for details. |
| --define_macro=<name>[(parameter-list)][=value] -D<name>[(parameter-list)][=value] |
Define macro <name> as value. If "=value" is omitted, define <name> as 1. |
| --undefine_macro=<name> -U<name> |
Remove predefined macro <name>. |
| --preinclude=<file> | Include file at the beginning of compilation.
NOTE: To simplify the integration in existing build environments other standard compiler options (e.g. GCC -include<file>, MSVC /FI@<file>) with similar meaning are also recognized and processed the same way. |
| --compatibility=<string> | Vendor compatibility mode. String can be "microsoft", "generic" or "gnu". Default is "generic". When "Microsoft" is set, the compiler supports a number of extensions to the C or C++ language that are compatible with the Microsoft family of compilers. "gnu" - instructs the compiler to support language extensions compatible with the Gnu family of compilers. |
| --no_warning | Suppress all warnings in the compilation phase. |
| --macros | Resolve macro (preprocessor define) constant value. Pass this flag only if you intend to do script based testing. |
| --documentation | Extract doxygen style source documentation. |
| --output=<path> -o<path> |
Output file or directory. The default is the current directory. |
| --targ_big_endian | Target uses a big endian by representation. The default is little endian. |
| --targ_plain_char_is_unsigned | Target uses unsigned chars to represent “plain” char. The default is signed. |
| --targ_adaptive_enum | Target has adaptive enums. The default is no adaptive enums. |
| --targ_pack_alignment=<align> | Target struct pack alignment. The default is 16. Possible values are 1, 2, 4, 8 or 16. |
| --targ_sizeof_char=<size> | Target platform size of char. Default is 1. Possible values are 1, 2, 4, 8, or 16. |
| --targ_alignof_char=<align> | Target platform alignment of char. Default is 1. Possible values are 1, 2, 4, 8 or 16. |
| --targ_sizeof_short=<size> | Default is 2. |
| --targ_alignof_short=<align> | Default is 2. |
| --targ_sizeof_int=<size> | Default is 4. |
| --targ_alignof_int=<align> | Default is 4. |
| --targ_sizeof_long=<size> | Default is 4. |
| --targ_alignof_long=<align> | Default is 4. |
| --targ_sizeof_long_long=<size> | Default is 8. |
| --targ_alignof_long_long=<align> | Default is 8. |
| --targ_sizeof_float=<size> | Default is 4. |
| --targ_alignof_float=<align> | Default is 4. |
| --targ_sizeof_double=<size> | Default is 8. |
| --targ_alignof_double=<align> | Default is 8. |
| --targ_sizeof_long_double=<size> | Default is 8 |
| --targ_alignof_long_double=<align> | Default is 8. |
| --targ_bool_int_kind=<typename> | Default is "char". |
| --targ_wchar_t_int_kind=<typename> | Default is "unsigned short". |
| --targ_size_t_int_kind=<typename> | Default is "unsigned int". |
| --targ_ptrdiff_t_int_kind=<typename> | Default is "int". |
| --options_file=<file> | A file that contains command line options. The format is the same as the command line with the only addition that it could be split on multiple lines. A line starting with "#" or ";" symbol is ignored.
This option is necessary if the length of the command line string exceeds system limits. Otherwise it is provided only as a convenience. NOTE: To simplify the integration in existing build environments other standard compiler options (e.g. ARM --via=<file>, GCC @<file>, MSVC @<file>) with similar meaning are also recognized and processed the same way. |
Note: The standard Platform SDKs shipped with the Framework contain a set of options files with predefined target settings for several popular CPUs. Please consider using one of them instead of explicitly passing --targ_* options on the command line.
Search Path
s2scompile by default looks in several different places for headers. It looks for headers requested with #include <file> in:
$(STRIDE_DIR)/SDK/Runtime
Where $(STRIDE_DIR) is the location where the STRIDE packages are installed following recommended directory layout.
When microsoft mode is specified and $(INCLUDE) enviroment variable is defined (as a ";" separated path list) then all of its entries are looked in for headers requested with #include <file>.
When gnu mode is specified and $(CPATH) and/or $(C_INCLUDE_PATH) (or $(CPLUS_INCLUDE_PATH) for C++) enviroment variables are defined (as a ":" separated path list) then all of its entries are looked in for headers requested with #include <file>. In addition if $(TARGET_CPP) specifies the target GNU cpp (GCC preprocessor or a command line equivalent) it is queried and any given path by it is looked in.
You can add to this list, before any of the default places, by using the -I<dir> option.
You can prevent s2scompile from searching any of the default directories with the --no_stdinc option. -I options are not ignored as described above when --no_stdinc is in effect.
s2scompile looks for headers requested with #include "file" first in the directory containing the current file, then in the same places it would have looked for a header requested with angle brackets.
Examples
Refer to the Compiling section of the Build Tools Examples.