From dcc50b9967b96da371412867b385811eb57f0497 Mon Sep 17 00:00:00 2001 From: Eli Schwartz Date: Wed, 30 Nov 2022 18:17:33 -0500 Subject: docs: clarify that prog.full_path has potentially valid uses Claiming that "it should literally never be used ever no matter what" is confusing and wrong -- it's definitely useful sometimes, but does result in downsides, like not tracking inter-target dependencies correctly. Ref: #10901 --- docs/yaml/objects/external_program.yaml | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/yaml/objects/external_program.yaml b/docs/yaml/objects/external_program.yaml index f4064771d..923cb54b7 100644 --- a/docs/yaml/objects/external_program.yaml +++ b/docs/yaml/objects/external_program.yaml @@ -15,8 +15,11 @@ methods: Returns a string pointing to the script or executable. - **NOTE:** You should not need to use this method. Passing the object itself - should work in all cases. + **NOTE:** You should not usually need to use this method. Passing the + object itself should work in most contexts where a program can appear, + and allows Meson to setup inter-target dependencies correctly. Only + use this if you specifically need a string, such as when embedding a + program path into a header file. For example: @@ -38,8 +41,11 @@ methods: description: | Returns a string pointing to the script or executable. - **NOTE:** You should not need to use this method. Passing the object itself - should work in all cases. + **NOTE:** You should not usually need to use this method. Passing the + object itself should work in most contexts where a program can appear, + and allows Meson to setup inter-target dependencies correctly. Only + use this if you specifically need a string, such as when embedding a + program path into a header file. For example: -- cgit v1.2.3