Slight improvement for lazbuild

[n7800]

   MYNEWVAR=($ lazbuild __arg_to_resolve__  --  $MYVAR )
where all the text after the -- is treated as input

I remember this argument in 7-zip. I don't like this option because the order of the arguments becomes important. Some people prefer to enter the arguments first and then the file. This will become impossible here.

You can enter some kind of escape character, but the first option is certainly better. You can specify text, or you can specify nothing, and then stdin will be read (if I understood Martin correctly):

Code: Bash  [Select][+][-]

1. lazbuild project1.lpi --get-expand-text="text with macros"
2. cat mydata | lazbuild project1.lpi --get-expand-text

Another option is to specify a different argument to read from standard input:

Code: Bash  [Select][+][-]

1. # --get-expand-text
2. lazbuild project1.lpi --get-expand-text="text with macros"
3. # --get-expand-stdin
4. cat mydata | lazbuild project1.lpi --get-expand-stdin

[Martin_fr]

Many tools have a mandatory command
- 7zip takes a one letter to specify what action (add, extract, ...)
- tar takes the action as normal param -x -z ...
- svn, git take a word...

lazbuild has a default action, which makes it harder to have a choice of action. And also introducing a keyword iirc wont work, because it can't be distinguished from other data (e.g. the project name / iirc).

-----

About the order.

I don't say there can't be an argument
 --text=escaped-text
Such an argument can be, and should be.

 --
is an additional argument, and by making it mandatory the last, anything thereafter does not need escaping.

--stdin
is used afaik by some other tools


Now if you have the choice of where the text should come from, you can have 3 commands

--expand-text="foo"
--expand-stdin
--expand-til-eol

That does blow up the amount of commands that there will be (especially if others may need the same).

So therefore, I though

--expand  --text=foo
--expand  --stdin
--expand  -- foo bar

Of course the names are just samples...


As to the choice between

--expand-macros
--action=expand-macros  or --cmd=expand-macros

or some other syntax....
That is another choice.

Making a distinction between the action and the data/options.


Also it needs decisions what happens if more than one action is specified.
Could be forbidden.
Could be allowed. => but then which option/data belongs to which action?

E.g listing pathes and macros can be done by one invocation. Done in the order in which the 2 are specified. But what if a buildmode is given, does it affect both? Could you expand twice for diff build modes?

It doesn't have to be implemented, not even finally decided today.

But if we know that lazbuild becomes more and more powerful, and will have more and more complex options, then we should think about designing the interface how to access it all.

[JuhaManninen]

Now if you have the choice of where the text should come from, you can have 3 commands

--expand-text="foo"
--expand-stdin
--expand-til-eol

That does blow up the amount of commands that there will be (especially if others may need the same).

What other commands would need input from --stdin?
Yet I agree, an explicit --stdin parameter would be intuitive and it is already used in some other cmd line tools.

The --expand-til-eol sounds very hypothetical. When would it be needed?

Making a distinction between the action and the data/options.

The big distinction happens between commands that build a project which is the original purpose of LazBuild, and the new commands that just show data.
Thus I like the idea of having a --get... prefix in those new commands. It indicates they only get and view data. They do not affect the building process.

[Martin_fr]

The big distinction happens between commands that build a project which is the original purpose of LazBuild, and the new commands that just show data.
Thus I like the idea of having a --get... prefix in those new commands. It indicates they only get and view data. They do not affect the building process.

What about using lazbuild, to build an run a test project, and return the result for "git bisect"?

The action would be something like "run" and potentially an option to change result codes to match bisect expectation.
Something like --get-run-result ? IMHO not.

Of course "run" doesn't replace "build". It extends it. But still. There may be something like
- checking validity of the lpi file (file can be read)
- updating lpi to latest format
- downgrading to compatible
- checking compiler options (-gv and -gh can not be given together)
- creating/changing a buildmode and setting options
- copy/export project
- ....

They don't work to well with "--get-...."

(Again, they may or may not get implemented, but if the command line interface is extended now, then maybe it better is done in a way that allows for as many extensions as possible, while still keeping some structured approach)


And getting paths or macros does not have to suppress build. In the help is has to be repeatedly pointed out for each option that they do that.
Otherwise a user might well assume that they get printed for the build that is performed at the same time.

[Martin_fr]

The --expand-til-eol sounds very hypothetical. When would it be needed?

https://unix.stackexchange.com/questions/11376/what-does-double-dash-mean

It is not exactly the same use. But it has the "no more need to escape (certain) special chars" (in that case the leading dash for params).

In our case the only arg after it would be the text to be processed..
So if text is in an env variable, then that could be
  NEWVAR= $( lazbuild --expand  --  $VAR )

If $VAR has spaces, quotes, ...: no problem.
I don't know, maybe in shells that would be escaped (though if the content starts with a - ?). But if you pass it to TProcess as single command line...

[n7800]

Many tools have a mandatory command
- 7zip takes a one letter to specify what action (add, extract, ...)
- tar takes the action as normal param -x -z ...
- svn, git take a word...

lazbuild has a default action, which makes it harder to have a choice of action. And also introducing a keyword iirc wont work, because it can't be distinguished from other data (e.g. the project name / iirc).

The archive can both pack and unpack, so it needs to be given a command. lazbuild, as the name implies, builds, so it is logical that this is its default command, and the rest must be specified explicitly.

Also it needs decisions what happens if more than one action is specified.
Could be forbidden.
Could be allowed. => but then which option/data belongs to which action?

E.g listing pathes and macros can be done by one invocation. Done in the order in which the 2 are specified. But what if a buildmode is given, does it affect both? Could you expand twice for diff build modes?

Only one command should be allowed at a time. I don't see any benefit to using multiple values in scripts, how can the script separate them? Moreover, as you noticed, this leads to even more questions and possible hidden errors.

By the way, lazbuild already has 4 commands that cancel the build:

Code: Pascal  [Select][+][-]

1. --help
2. --version
3. --create-makefile
4. --add-package-link

Let me remind you that several such parameters already exist. Will they remain as an exception to maintain backward compatibility? Or will they also need to be specified in "--action"?

Of course "run" doesn't replace "build". It extends it. But still. There may be something like
- checking validity of the lpi file (file can be read)
- updating lpi to latest format
- downgrading to compatible
- checking compiler options (-gv and -gh can not be given together)
- creating/changing a buildmode and setting options
- copy/export project
- ....

They don't work to well with "--get-...."

If we need to add parameters, we will add something like: --set-build-mode, --check-lpi, --update-lpi and so on. This fits easily into the already existing --create-makefile and --add-package-link. In addition, all these words are verbs that denote actions.

Users can only learn about the parameters from the help, and there will be a clear list of "actions" and parameters for each of them. In helping, this division will be appropriate.

It seems to me that you underestimate users too much)) All Lazarus users are programmers. They'll figure it out easily.

[Martin_fr]

lazbuild has a default action,

The archive can both pack and unpack, so it needs to be given a command. lazbuild, as the name implies, builds, so it is logical that this is its default command, and the rest must be specified explicitly.

Yes, we agree, lazbuild has a default action.

IMHO, the more important to distinguish anything that replaces this default.
Most parameters are "modifiers", they affect "how to build" or "what to build". They don't replace the "build" itself.

Only one command should be allowed at a time. I don't see any benefit to using multiple values in scripts, how can the script separate them? Moreover, as you noticed, this leads to even more questions and possible hidden errors.

In general, yes. But it wont hurt to think about it for the interface, in case something comes up, that changes that.

Like printing the settings used for a build into a file for later usage.
Then you may want to do all of it, build, and get-this and get-that, .....
I don't encourage it, but I don't know what will be in 2, 5 or 10.37 years.

Let me remind you that several such parameters already exist. Will they remain as an exception to maintain backward compatibility? Or will they also need to be specified in "--action"?

Yes, we already have a mess. And yes, most of it will likely have to be kept for compatibility.

Does that mean we have to make it even messier? Or should we at some point try to get some concept into this?

If we need to add parameters, we will add something like: --set-build-mode, --check-lpi, --update-lpi and so on. This fits easily into the already existing --create-makefile and --add-package-link. In addition, all these words are verbs that denote actions.

Users can only learn about the parameters from the help, and there will be a clear list of "actions" and parameters for each of them. In helping, this division will be appropriate.

It seems to me that you underestimate users too much)) All Lazarus users are programmers. They'll figure it out easily.

Yes, we could... And today already something like "--create-makefile" does it
- create a makefile that it will then use to do the build? (because, the default - unless explicitly disabled - should be to build)
- just create the makefile

Yes, the answer is in the doc/help. But self-explaining params would be nice.


To be honest, I don't fancy the extra long --action=
But I even less fancy the "mixing it all together".

So if there is another idea, which solves both....

[Martin_fr]

Btw, about the idea with multiple commands, something like this would work (and probably even be compatible with what we currently have, at least so long as current syntax has one action only

Code: Text  [Select][+][-]

1. lazbuild   [options for all actions]  ACTION-1 [options for action 1 only]  ACTION-2 [options for action 2 only]

Yes of course that can be done with the --get-.. --update-... style. But that be really bad...

There could be a divider between actions

Code: Text  [Select][+][-]

1. lazbuild   [options for all actions]  -+- [options for action 1 only]  ACTION-1  [options for action 1 only]  -+- ACTION-2 [options for action 2 only]

Neither needs to be decided yet. If for now, the rule is: only one action, then both of the above will be backward compatible, if ever we would want them.

[JuhaManninen]

Code: Text  [Select][+][-]

1. lazbuild   [options for all actions]  ACTION-1 [options for action 1 only]  ACTION-2 [options for action 2 only]

Yes of course that can be done with the --get-.. --update-... style. But that be really bad...

How would the actions be named if --get-... and --update-... are bad? Please give an example.

[Martin_fr]

How would the actions be named if --get-... and --update-... are bad? Please give an example.

Well that is the idea needed.

A non prefixed word (e.g. a verb, or group of words) would be easy to understand. But IIRC it can be confused with the filename.
"lazbuild show buildmodes" => looks for a package called "show"

So we are limited already by past decisions.

- The only thing compatible is params starting with a dash. But that has downsides (as explained, unclear what is an "action replacing build" and "what does modify/add to build").
- The clear way is  --cmd= / But has the extra typing.
- Incompatible option: use non prefixed words


So as far as I can see, we only have choices that are bad.
We could start a new "lazbuild2" or "lazcmd" command. (same project, new buildmode, some ifdefs)

Anyway, if no one has any further ideas, then it is about choosing the least objectionable, which likely will be a very subjective choice.

I've given my 2 cents.

---
Btw, if the choice is made for --get and --update => should we at least decide, that (at least any newly introduced one) must be the very first argument. No particular reason (as it is outside my preference anyway), just a gut feeling.

[TRon]

A non prefixed word (e.g. a verb, or group of words) would be easy to understand. But IIRC it can be confused with the filename.
"lazbuild show buildmodes" => looks for a package called "show"

So we are limited already by past decisions.

That is why you need to think about these kind of things before actually implementing. Because it is another functionality the most sane things to do imo would be to create a separate command that is addressing the evaluation.

If you want to add it to lazbuild and the parameters can be conflicting then make it so that the parameters are explicit. Use a keyword to indicate the meaning of the argument that follows, e.g. lazbuild command build blah blah or lazbuild command evaluate. I used the keyword command here but it can ofc be anything that you want. For commandline programs that are going to perform multiple actions I would even suggest to add support for such commands from the get-go, You can always decide later that one of the actions is becoming the default  action so that the action/command keyword itself can be omitted.

2 cents

[n7800]

Btw, if the choice is made for --get and --update => should we at least decide, that (at least any newly introduced one) must be the very first argument. No particular reason (as it is outside my preference anyway), just a gut feeling.

On the one hand, it is logical to specify the project file as the first argument, because without specifying it, any command will be unimportant. No project - nothing to do.
On the other hand, it is logical to indicate what you are planning to do. Although, in our case, this may be the default command, that is, it may be absent.

I don’t think we need to restrict the user unnecessarily - let him write as he sees fit. It is usually assumed that the order of the arguments does not matter.

I can give an example of FFMPEG syntax in which the position of the argument is very important. The same argument placed in different places will have different effects. This is all very complicated and not obvious.

[n7800]

That is why you need to think about these kind of things before actually implementing. Because it is another functionality the most sane things to do imo would be to create a separate command that is addressing the evaluation.

Regarding the separate utility, I said:

It might not be a good idea to have lazbuild do this. However, who else? It still does this on every build. Why create and maintain a separate utility? Due to various errors (different version or working directory), it may return different information than lazbuild. Let lazbuild do it.

And I don't think a "bad" name is a reason to develop a new tool that will do almost the same thing.

If you want to add it to lazbuild and the parameters can be conflicting then make it so that the parameters are explicit.

Almost all utilities have incompatible parameters - this is not a problem.

[n7800]

By the way, let's assume for a moment that we could use syntax like 7z:

Code: Bash  [Select][+][-]

1. lazbuild <cmd> <file> [args]

Then what lazbuild should do in such cases:

Code: Bash  [Select][+][-]

1. lazbuild --create-makefile project1.lpi
2. lazbuild project1.lpi --create-makefile

In the first line everything is correct, but in the second line the file and command are "rearranged". And so what? It is still absolutely clear what the user wanted. I see no reason to call such a command invalid.


And if the build command were not the default, then we would have an unnecessary repetition of the word "build":

Code: Bash  [Select][+][-]

1. lazbuild build project1.lpi

[Martin_fr]

Then what lazbuild should do in such cases:

Code: Bash  [Select][+][-]

1. lazbuild --create-makefile project1.lpi
2. lazbuild project1.lpi --create-makefile

In the first line everything is correct, but in the second line the file and command are "rearranged". And so what? It is still absolutely clear what the user wanted. I see no reason to call such a command invalid.

Really? What does he want to do?

Does he want to perform the default action (build), but in a modified way (create a makefile, and build using that)?