command line - ¿Debería imprimirse la línea de comando "use" en stdout o stderr?

command-line usage-message

Question

Al imprimir el "uso" de una aplicación, ¿debería hacerse en stdout o en stderr?

Dependiendo de la aplicación, he visto varios casos, pero no parece haber una regla. Tal vez estoy equivocado y hay una buena práctica. En ese caso, ¿qué es?

Answer 1

¿Debería imprimirse la línea de comando "use" en stdout o stderr?

Creo que depende de los estándares de codificación de la organización. Fuera de una organización, es probablemente uno de esos temas que se debaten sin parar, como cuál es el mejor sistema operativo, cuál es el mejor editor, cuál es la religión correcta, ...

Navegando convenciones de código Java (SEPT 1997), Java no lo especifica. No hay respuesta, y será debatida sin fin.

De acuerdo con los estándares de codificación de GNU , debe imprimirse en salida estándar:

4.7.2 --ayuda

La opción estándar --help debería dar como resultado una breve documentación sobre cómo invocar el programa, en la salida estándar, luego salir exitosamente. Se deben ignorar otras opciones y argumentos una vez que se ve esto, y el programa no debe realizar su función normal.

Cerca del final de la salida de la opción ''- help'', coloque líneas que den la dirección de correo electrónico para informes de errores, la página de inicio del paquete (normalmente '' http://www.gnu.org/software/pkg '', y la página general para obtener ayuda con el uso de programas GNU. El formato debería ser así:

Report bugs to: mailing-address
pkg home page: <http://www.gnu.org/software/pkg/>
General help using GNU software: <http://www.gnu.org/gethelp/>

Está bien mencionar otras listas de correo y páginas web apropiadas.

Aquí está el tema relacionado de "versión" . También es de la guía de codificación GNU, y también escribe en salida estándar:

4.7.1 --versión

La opción estándar de conversión debe indicar al programa que imprima información sobre su nombre, versión, origen y estado legal, todo en salida estándar, y luego salir exitosamente. Se deben ignorar otras opciones y argumentos una vez que se ve esto, y el programa no debe realizar su función normal.

La primera línea debe ser fácil de analizar para un programa; el número de versión correcto comienza después del último espacio. Además, contiene el nombre canónico para este programa, en este formato:

GNU Emacs 19.30

El nombre del programa debe ser una cadena constante; no lo calcule a partir de argv [0]. La idea es indicar el nombre estándar o canónico para el programa, no su nombre de archivo. Hay otras formas de averiguar el nombre exacto del archivo donde se encuentra un comando en PATH.

Si el programa es una parte subsidiaria de un paquete más grande, menciona el nombre del paquete entre paréntesis, como este:

emacsserver (GNU Emacs) 19.30

Si el paquete tiene un número de versión que es diferente al número de versión de este programa, puede mencionar el número de versión del paquete justo antes del paréntesis cerrado.

Si necesita mencionar los números de versión de las bibliotecas que se distribuyen por separado del paquete que contiene este programa, puede hacerlo imprimiendo una línea adicional de información de versión para cada biblioteca que desee mencionar. Use el mismo formato para estas líneas que para la primera línea.

Por favor, no mencione todas las bibliotecas que el programa utiliza "solo para completar", que produciría un montón de desorden inútil. Mencione los números de versión de la biblioteca solo si encuentra que en la práctica son muy importantes para la depuración.

La siguiente línea, después de la línea o las líneas del número de versión, debe ser un aviso de copyright. Si se solicita más de un aviso de copyright, coloque cada uno en una línea separada.

A continuación, debe seguir una línea que indica la licencia, preferiblemente utilizando una de las abreviaturas a continuación, y una breve declaración de que el programa es software libre, y que los usuarios pueden copiarlo y modificarlo. También mencione que no hay garantía, en la medida permitida por la ley. Vea la redacción recomendada a continuación.

Está bien terminar la salida con una lista de los principales autores del programa, como una forma de dar crédito.

Aquí hay un ejemplo de resultados que sigue estas reglas:

GNU hello 2.3
Copyright (C) 2007 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

...

Answer 2

Esto solo puede ser una opinión, pero creo que escribir en stderr es lo mejor que se puede hacer. De esta forma, el mensaje de uso aparece si el usuario comete un error incluso si la salida normal ha sido redirigida.

Answer 3

Estoy de acuerdo en que el "uso" explícitamente solicitado (a través de una opción -h, -? U --help) debería ir a stdout mientras que el "uso" que se imprime en respuesta a una sintaxis incorrecta u otros errores debería ir a stderr.

Sin embargo, tenga en cuenta que la biblioteca popt cada vez más popular (que maneja el análisis de línea de comandos, su nombre significa "opciones de análisis sintáctico") incluye un recurso para la ayuda generada automáticamente y que siempre envía eso a stderr. Cito la página de popt man:

Cuando --usage o --help se pasan a programas que usan la ayuda automática de popt, popt muestra el mensaje apropiado en stderr tan pronto como encuentra la opción, y sale del programa con un código de retorno de 0.

Creo que esto es un error, pero el problema es que POSIX (o ISO C, a la que difiere) nunca definió lo que significaba "salida de diagnóstico". Solo lea ''man stderr'' o POSIX.1-2008 .

Answer 4

Según yo, el criterio es cómo emergencia es la información. Si necesita reacción o atención inmediata, lo pongo en stderr (porque no está protegido). Si de alguna manera es informativo y no considera ningún error, es para stdout.

Answer 5

Siempre me molestan los programas que tienen muchas opciones que no caben en la pantalla, pero cuando se ejecutan como program --help | less program --help | less , no puedo ver nada ya que la ayuda fue enviada a stderr .

Me gusta la idea del uso explícitamente solicitado (es decir, la opción de --help ) debería enviar la salida a stdout . En el caso de las opciones no válidas, creo que no es necesario mostrar información de uso detallada. Definitivamente debe haber un mensaje de error como la Invalid option "--some-option". Run "program --help" for usage information. Invalid option "--some-option". Run "program --help" for usage information. enviado a stderr . Si el programa decide generar información de uso de forma predeterminada sobre opciones no válidas o si se invoca sin opciones, creo que debería haber un breve mensaje de error quejándose de un uso no válido, pero la ayuda en sí misma puede ir a stdout .

Answer 6

Usaría STDERR ya que simplemente ponerlo en STDOUT podría causar problemas con la salida por canalización y aparecerá en los registros de cronjobs para que notes el error más fácil.

Answer 7

si - --help luego stdout, else stderr. Aquí está el código JCommander para usuarios de Java:

MyOptions myOptions = new MyOptions();
JCommander jCommander = new JCommander(myOptions);

try {
    jCommander.parse(args);
} catch (ParameterException exp) {
    /* print the exp here if you want */
    StringBuilder sb = new StringBuilder();
    jCommander.usage(sb);
    System.err.println(sb.toString());
    System.exit(1);
}

if(myOptions.isHelp()) {
    jCommander.usage();
    System.exit(0);
}

Answer 8

Nunca pensé en ello, pero ¿por qué no escribir las instrucciones de uso para stderr si el programa se llamó sin argumentos o con argumentos incorrectos, y escribirlo en stdout cuando se llama con un argumento --help (o similar)? De esta forma, si el uso se muestra debido a un error, se envía a stderr, y si no es un error porque el usuario lo solicitó, se envía a stdout. Parece lógico, de alguna manera.