OLD | NEW |
1 # GN Reference | 1 # GN Reference |
2 | 2 |
3 *This page is automatically generated from* `gn help --markdown all`. | 3 *This page is automatically generated from* `gn help --markdown all`. |
4 | 4 |
5 ## **\--args**: Specifies build arguments overrides. | 5 ## **\--args**: Specifies build arguments overrides. |
6 | 6 |
7 ``` | 7 ``` |
8 See "gn help buildargs" for an overview of how build arguments work. | 8 See "gn help buildargs" for an overview of how build arguments work. |
9 | 9 |
10 Most operations take a build directory. The build arguments are taken | 10 Most operations take a build directory. The build arguments are taken |
(...skipping 2712 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
2723 ``` | 2723 ``` |
2724 | 2724 |
2725 ### **Tool variables** | 2725 ### **Tool variables** |
2726 | 2726 |
2727 ``` | 2727 ``` |
2728 command [string with substitutions] | 2728 command [string with substitutions] |
2729 Valid for: all tools (required) | 2729 Valid for: all tools (required) |
2730 | 2730 |
2731 The command to run. | 2731 The command to run. |
2732 | 2732 |
| 2733 default_output_dir [string with substitutions] |
| 2734 Valid for: linker tools |
| 2735 |
| 2736 Default directory name for the output file relative to the |
| 2737 root_build_dir. It can contain other substitution patterns. |
| 2738 This will be the default value for the {{output_dir}} expansion |
| 2739 (discussed below) but will be overridden by the "output_dir" |
| 2740 variable in a target, if one is specified. |
| 2741 |
| 2742 GN doesn't do anything with this string other than pass it |
| 2743 along, potentially with target-specific overrides. It is the |
| 2744 tool's job to use the expansion so that the files will be in |
| 2745 the right place. |
| 2746 |
2733 default_output_extension [string] | 2747 default_output_extension [string] |
2734 Valid for: linker tools | 2748 Valid for: linker tools |
2735 | 2749 |
2736 Extension for the main output of a linkable tool. It includes | 2750 Extension for the main output of a linkable tool. It includes |
2737 the leading dot. This will be the default value for the | 2751 the leading dot. This will be the default value for the |
2738 {{output_extension}} expansion (discussed below) but will be | 2752 {{output_extension}} expansion (discussed below) but will be |
2739 overridden by by the "output extension" variable in a target, | 2753 overridden by by the "output extension" variable in a target, |
2740 if one is specified. Empty string means no extension. | 2754 if one is specified. Empty string means no extension. |
2741 | 2755 |
2742 GN doesn't actually do anything with this extension other than | 2756 GN doesn't actually do anything with this extension other than |
2743 pass it along, potentially with target-specific overrides. One | 2757 pass it along, potentially with target-specific overrides. One |
2744 would typically use the {{output_extension}} value in the | 2758 would typically use the {{output_extension}} value in the |
2745 "outputs" to read this value. | 2759 "outputs" to read this value. |
2746 | 2760 |
2747 Example: default_output_extension = ".exe" | 2761 Example: default_output_extension = ".exe" |
2748 | 2762 |
2749 depfile [string] | 2763 depfile [string with substitutions] |
2750 Valid for: compiler tools (optional) | 2764 Valid for: compiler tools (optional) |
2751 | 2765 |
2752 If the tool can write ".d" files, this specifies the name of | 2766 If the tool can write ".d" files, this specifies the name of |
2753 the resulting file. These files are used to list header file | 2767 the resulting file. These files are used to list header file |
2754 dependencies (or other implicit input dependencies) that are | 2768 dependencies (or other implicit input dependencies) that are |
2755 discovered at build time. See also "depsformat". | 2769 discovered at build time. See also "depsformat". |
2756 | 2770 |
2757 Example: depfile = "{{output}}.d" | 2771 Example: depfile = "{{output}}.d" |
2758 | 2772 |
2759 depsformat [string] | 2773 depsformat [string] |
(...skipping 41 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
2801 runtime_link_output. Otherwise, the first entry in the | 2815 runtime_link_output. Otherwise, the first entry in the |
2802 outputs list should always be the main output which will be | 2816 outputs list should always be the main output which will be |
2803 linked to. | 2817 linked to. |
2804 | 2818 |
2805 Example for a compiler tool that produces .obj files: | 2819 Example for a compiler tool that produces .obj files: |
2806 outputs = [ | 2820 outputs = [ |
2807 "{{source_out_dir}}/{{source_name_part}}.obj" | 2821 "{{source_out_dir}}/{{source_name_part}}.obj" |
2808 ] | 2822 ] |
2809 | 2823 |
2810 Example for a linker tool that produces a .dll and a .lib. The | 2824 Example for a linker tool that produces a .dll and a .lib. The |
2811 use of {{output_extension}} rather than hardcoding ".dll" | 2825 use of {{target_output_name}}, {{output_extension}} and |
2812 allows the extension of the library to be overridden on a | 2826 {{output_dir}} allows the target to override these values. |
2813 target-by-target basis, but in this example, it always | |
2814 produces a ".lib" import library: | |
2815 outputs = [ | 2827 outputs = [ |
2816 "{{root_out_dir}}/{{target_output_name}}{{output_extension}}", | 2828 "{{output_dir}}/{{target_output_name}}{{output_extension}}", |
2817 "{{root_out_dir}}/{{target_output_name}}.lib", | 2829 "{{output_dir}}/{{target_output_name}}.lib", |
2818 ] | 2830 ] |
2819 | 2831 |
2820 link_output [string with substitutions] | 2832 link_output [string with substitutions] |
2821 depend_output [string with substitutions] | 2833 depend_output [string with substitutions] |
2822 runtime_link_output [string with substitutions] | 2834 runtime_link_output [string with substitutions] |
2823 Valid for: "solink" only (optional) | 2835 Valid for: "solink" only (optional) |
2824 | 2836 |
2825 These three files specify which of the outputs from the solink | 2837 These three files specify which of the outputs from the solink |
2826 tool should be used for linking and dependency tracking. These | 2838 tool should be used for linking and dependency tracking. These |
2827 should match entries in the "outputs". If unspecified, the | 2839 should match entries in the "outputs". If unspecified, the |
2828 first item in the "outputs" array will be used for all. See | 2840 first item in the "outputs" array will be used for all. See |
2829 "Separate linking and dependencies for shared libraries" | 2841 "Separate linking and dependencies for shared libraries" |
2830 below for more. If link_output is set but runtime_link_output | 2842 below for more. If link_output is set but runtime_link_output |
2831 is not set, runtime_link_output defaults to link_output. | 2843 is not set, runtime_link_output defaults to link_output. |
2832 | 2844 |
2833 On Windows, where the tools produce a .dll shared library and | 2845 On Windows, where the tools produce a .dll shared library and |
2834 a .lib import library, you will want the first two to be the | 2846 a .lib import library, you will want the first two to be the |
2835 import library and the third one to be the .dll file. | 2847 import library and the third one to be the .dll file. |
2836 On Linux, if you're not doing the separate linking/dependency | 2848 On Linux, if you're not doing the separate linking/dependency |
2837 optimization, all of these should be the .so output. | 2849 optimization, all of these should be the .so output. |
2838 | 2850 |
2839 output_prefix [string] | 2851 output_prefix [string] |
2840 Valid for: Linker tools (optional) | 2852 Valid for: Linker tools (optional) |
(...skipping 89 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
2930 {{output}} | 2942 {{output}} |
2931 The relative path and name of the output(s) of the current | 2943 The relative path and name of the output(s) of the current |
2932 build step. If there is more than one output, this will expand | 2944 build step. If there is more than one output, this will expand |
2933 to a list of all of them. | 2945 to a list of all of them. |
2934 Example: "out/base/my_file.o" | 2946 Example: "out/base/my_file.o" |
2935 | 2947 |
2936 {{target_gen_dir}} | 2948 {{target_gen_dir}} |
2937 {{target_out_dir}} | 2949 {{target_out_dir}} |
2938 The directory of the generated file and output directories, | 2950 The directory of the generated file and output directories, |
2939 respectively, for the current target. There is no trailing | 2951 respectively, for the current target. There is no trailing |
2940 slash. | 2952 slash. See also {{output_dir}} for linker tools. |
2941 Example: "out/base/test" | 2953 Example: "out/base/test" |
2942 | 2954 |
2943 {{target_output_name}} | 2955 {{target_output_name}} |
2944 The short name of the current target with no path information, | 2956 The short name of the current target with no path information, |
2945 or the value of the "output_name" variable if one is specified | 2957 or the value of the "output_name" variable if one is specified |
2946 in the target. This will include the "output_prefix" if any. | 2958 in the target. This will include the "output_prefix" if any. |
2947 See also {{label_name}}. | 2959 See also {{label_name}}. |
2948 Example: "libfoo" for the target named "foo" and an | 2960 Example: "libfoo" for the target named "foo" and an |
2949 output prefix for the linker tool of "lib". | 2961 output prefix for the linker tool of "lib". |
2950 | 2962 |
(...skipping 62 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
3013 {{libs}} | 3025 {{libs}} |
3014 Expands to the list of system libraries to link to. Each will | 3026 Expands to the list of system libraries to link to. Each will |
3015 be prefixed by the "lib_prefix". | 3027 be prefixed by the "lib_prefix". |
3016 | 3028 |
3017 As a special case to support Mac, libraries with names ending in | 3029 As a special case to support Mac, libraries with names ending in |
3018 ".framework" will be added to the {{libs}} with "-framework" | 3030 ".framework" will be added to the {{libs}} with "-framework" |
3019 preceeding it, and the lib prefix will be ignored. | 3031 preceeding it, and the lib prefix will be ignored. |
3020 | 3032 |
3021 Example: "-lfoo -lbar" | 3033 Example: "-lfoo -lbar" |
3022 | 3034 |
| 3035 {{output_dir}} |
| 3036 The value of the "output_dir" variable in the target, or the |
| 3037 the value of the "default_output_dir" value in the tool if the |
| 3038 target does not override the output directory. This will be |
| 3039 relative to the root_build_dir and will not end in a slash. |
| 3040 Will be "." for output to the root_build_dir. |
| 3041 |
| 3042 This is subtly different than {{target_out_dir}} which is |
| 3043 defined by GN based on the target's path and not overridable. |
| 3044 {{output_dir}} is for the final output, {{target_out_dir}} is |
| 3045 generally for object files and other outputs. |
| 3046 |
| 3047 Usually {{output_dir}} would be defined in terms of either |
| 3048 {{target_out_dir}} or {{root_out_dir}} |
| 3049 |
3023 {{output_extension}} | 3050 {{output_extension}} |
3024 The value of the "output_extension" variable in the target, | 3051 The value of the "output_extension" variable in the target, |
3025 or the value of the "default_output_extension" value in the | 3052 or the value of the "default_output_extension" value in the |
3026 tool if the target does not specify an output extension. | 3053 tool if the target does not specify an output extension. |
3027 Example: ".so" | 3054 Example: ".so" |
3028 | 3055 |
3029 {{solibs}} | 3056 {{solibs}} |
3030 Extra libraries from shared library dependencide not specified | 3057 Extra libraries from shared library dependencide not specified |
3031 in the {{inputs}}. This is the list of link_output files from | 3058 in the {{inputs}}. This is the list of link_output files from |
3032 shared libraries (if the solink tool specifies a "link_output" | 3059 shared libraries (if the solink tool specifies a "link_output" |
(...skipping 35 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
3068 | 3095 |
3069 You will need to specify | 3096 You will need to specify |
3070 restat = true | 3097 restat = true |
3071 in the linker tool to make this work, so Ninja will detect if the | 3098 in the linker tool to make this work, so Ninja will detect if the |
3072 timestamp of the dependency file has changed after linking (otherwise | 3099 timestamp of the dependency file has changed after linking (otherwise |
3073 it will always assume that running a command updates the output): | 3100 it will always assume that running a command updates the output): |
3074 | 3101 |
3075 tool("solink") { | 3102 tool("solink") { |
3076 command = "..." | 3103 command = "..." |
3077 outputs = [ | 3104 outputs = [ |
3078 "{{root_out_dir}}/{{target_output_name}}{{output_extension}}", | 3105 "{{output_dir}}/{{target_output_name}}{{output_extension}}", |
3079 "{{root_out_dir}}/{{target_output_name}}{{output_extension}}.TOC", | 3106 "{{output_dir}}/{{target_output_name}}{{output_extension}}.TOC", |
3080 ] | 3107 ] |
3081 link_output = | 3108 link_output = |
3082 "{{root_out_dir}}/{{target_output_name}}{{output_extension}}" | 3109 "{{output_dir}}/{{target_output_name}}{{output_extension}}" |
3083 depend_output = | 3110 depend_output = |
3084 "{{root_out_dir}}/{{target_output_name}}{{output_extension}}.TOC" | 3111 "{{output_dir}}/{{target_output_name}}{{output_extension}}.TOC" |
3085 restat = true | 3112 restat = true |
3086 } | 3113 } |
3087 | 3114 |
3088 ``` | 3115 ``` |
3089 | 3116 |
3090 ### **Example** | 3117 ### **Example** |
3091 | 3118 |
3092 ``` | 3119 ``` |
3093 toolchain("my_toolchain") { | 3120 toolchain("my_toolchain") { |
3094 # Put these at the top to apply to all tools below. | 3121 # Put these at the top to apply to all tools below. |
(...skipping 1558 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
4653 | 4680 |
4654 ``` | 4681 ``` |
4655 On Windows: | 4682 On Windows: |
4656 libs = [ "ctl3d.lib" ] | 4683 libs = [ "ctl3d.lib" ] |
4657 | 4684 |
4658 On Linux: | 4685 On Linux: |
4659 libs = [ "ld" ] | 4686 libs = [ "ld" ] |
4660 | 4687 |
4661 | 4688 |
4662 ``` | 4689 ``` |
| 4690 ## **output_dir**: [directory] Directory to put output file in. |
| 4691 |
| 4692 ``` |
| 4693 For library and executable targets, overrides the directory for the |
| 4694 final output. This must be in the root_build_dir or a child thereof. |
| 4695 |
| 4696 This should generally be in the root_out_dir or a subdirectory thereof |
| 4697 (the root_out_dir will be the same as the root_build_dir for the |
| 4698 default toolchain, and will be a subdirectory for other toolchains). |
| 4699 Not putting the output in a subdirectory of root_out_dir can result |
| 4700 in collisions between different toolchains, so you will need to take |
| 4701 steps to ensure that your target is only present in one toolchain. |
| 4702 |
| 4703 Normally the toolchain specifies the output directory for libraries |
| 4704 and executables (see "gn help tool"). You will have to consult that |
| 4705 for the default location. The default location will be used if |
| 4706 output_dir is undefined or empty. |
| 4707 |
| 4708 ``` |
| 4709 |
| 4710 ### **Example** |
| 4711 |
| 4712 ``` |
| 4713 shared_library("doom_melon") { |
| 4714 output_dir = "$root_out_dir/plugin_libs" |
| 4715 ... |
| 4716 } |
| 4717 |
| 4718 |
| 4719 ``` |
4663 ## **output_extension**: Value to use for the output's file extension. | 4720 ## **output_extension**: Value to use for the output's file extension. |
4664 | 4721 |
4665 ``` | 4722 ``` |
4666 Normally the file extension for a target is based on the target | 4723 Normally the file extension for a target is based on the target |
4667 type and the operating system, but in rare cases you will need to | 4724 type and the operating system, but in rare cases you will need to |
4668 override the name (for example to use "libfreetype.so.6" instead | 4725 override the name (for example to use "libfreetype.so.6" instead |
4669 of libfreetype.so on Linux). | 4726 of libfreetype.so on Linux). |
4670 | 4727 |
4671 This value should not include a leading dot. If undefined, the default | 4728 This value should not include a leading dot. If undefined, the default |
4672 specified on the tool will be used. If set to the empty string, no | 4729 specified on the tool will be used. If set to the empty string, no |
(...skipping 1044 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
5717 sources. | 5774 sources. |
5718 | 5775 |
5719 See "gn help copy" and "gn help action_foreach" for more on how | 5776 See "gn help copy" and "gn help action_foreach" for more on how |
5720 this is applied. | 5777 this is applied. |
5721 | 5778 |
5722 ``` | 5779 ``` |
5723 | 5780 |
5724 ### **Placeholders** | 5781 ### **Placeholders** |
5725 | 5782 |
5726 ``` | 5783 ``` |
| 5784 This section discusses only placeholders for actions. There are other |
| 5785 placeholders used in the definition of tools. See "gn help tool" for |
| 5786 those. |
| 5787 |
5727 {{source}} | 5788 {{source}} |
5728 The name of the source file including directory (*). This will | 5789 The name of the source file including directory (*). This will |
5729 generally be used for specifying inputs to a script in the | 5790 generally be used for specifying inputs to a script in the |
5730 "args" variable. | 5791 "args" variable. |
5731 "//foo/bar/baz.txt" => "../../foo/bar/baz.txt" | 5792 "//foo/bar/baz.txt" => "../../foo/bar/baz.txt" |
5732 | 5793 |
5733 {{source_file_part}} | 5794 {{source_file_part}} |
5734 The file part of the source including the extension. | 5795 The file part of the source including the extension. |
5735 "//foo/bar/baz.txt" => "baz.txt" | 5796 "//foo/bar/baz.txt" => "baz.txt" |
5736 | 5797 |
(...skipping 92 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
5829 ** -q**: Quiet mode. Don't print output on success. | 5890 ** -q**: Quiet mode. Don't print output on success. |
5830 ** \--root**: Explicitly specify source root. | 5891 ** \--root**: Explicitly specify source root. |
5831 ** \--runtime-deps-list-file**: Save runtime dependencies for targets in file. | 5892 ** \--runtime-deps-list-file**: Save runtime dependencies for targets in file. |
5832 ** \--threads**: Specify number of worker threads. | 5893 ** \--threads**: Specify number of worker threads. |
5833 ** \--time**: Outputs a summary of how long everything took. | 5894 ** \--time**: Outputs a summary of how long everything took. |
5834 ** \--tracelog**: Writes a Chrome-compatible trace log to the given file. | 5895 ** \--tracelog**: Writes a Chrome-compatible trace log to the given file. |
5835 ** -v**: Verbose logging. | 5896 ** -v**: Verbose logging. |
5836 ** \--version**: Prints the GN version number and exits. | 5897 ** \--version**: Prints the GN version number and exits. |
5837 | 5898 |
5838 ``` | 5899 ``` |
OLD | NEW |