From b645a0c4b14b39ed9706f96e93c7fc41d569dbe1 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Wed, 7 Aug 2024 09:36:46 -0400 Subject: [PATCH 01/15] new command geturl --- doc/src/geturl.rst | 72 +++++++++++++++++++++++ src/EXTRA-COMMAND/geturl.cpp | 111 +++++++++++++++++++++++++++++++++++ src/EXTRA-COMMAND/geturl.h | 34 +++++++++++ 3 files changed, 217 insertions(+) create mode 100644 doc/src/geturl.rst create mode 100644 src/EXTRA-COMMAND/geturl.cpp create mode 100644 src/EXTRA-COMMAND/geturl.h diff --git a/doc/src/geturl.rst b/doc/src/geturl.rst new file mode 100644 index 0000000000..e75e5cd1bf --- /dev/null +++ b/doc/src/geturl.rst @@ -0,0 +1,72 @@ +.. index:: geturl + +geturl command +============== + +Syntax +"""""" + +.. code-block:: LAMMPS + + geturl url keyword args ... + +* url = URL of the file to download +* zero or more keyword argument pairs may be provided +* keyword = *output* or *verify* or *overwrite* + + .. parsed-literal:: + + *output* filename = write to *filename* instead of inferring the name from the URL + *verify* yes/no = verify SSL certificate and hostname if *yes*, do not if *no* + *overwrite* yes/no = if *yes* overwrite the output file in case it exists, do not if *no* + +Examples +"""""""" + +.. code-block:: LAMMPS + + geturl https://www.ctcms.nist.gov/potentials/Download/1990--Ackland-G-J-Vitek-V--Cu/2/Cu2.eam.fs + geturl https://github.com/lammps/lammps/blob/develop/bench/in.lj output in.bench-lj + +Description +""""""""""" + +Download a file from an URL to the local disk. This is implemented with +the `libcurl library `_ which supports a +large variety of protocols including "http", "https", "ftp", "scp", +"sftp", "file". The transfer will only be performed on MPI rank 0. + +The *output* keyword can be used to set the filename. By default, the last part +of the URL is used. + +The *verify* keyword allows to turn on or off whether ``libcurl`` will validate +the SSL certificate and hostname for encrypted connections. Turning this off +may be required when using a proxy or connecting to a server with a self-signed +SSL certificate. + +The *overwrite* keyword determines whether a file should be overwritten if it +already exists. If the argument is *no*, then the download will be skipped +if the file exists. + +---------- + +Restrictions +"""""""""""" + +This command is part of the EXTRA-COMMAND package. It is only enabled +if LAMMPS was built with that package. See the :doc:`Build package +` page for more info. It also requires that LAMMPS was +built with support for `the libcurl library +`_. See the page about :ref:`Compiling LAMMPS +with libcurl support ` for further info. If support for +libcurl is not included, using *geturl* will trigger an error. + +Related commands +"""""""""""""""" + +:doc:`shell ` + +Default +""""""" + +*verify* = yes, *overwrite* = yes diff --git a/src/EXTRA-COMMAND/geturl.cpp b/src/EXTRA-COMMAND/geturl.cpp new file mode 100644 index 0000000000..df46d0b723 --- /dev/null +++ b/src/EXTRA-COMMAND/geturl.cpp @@ -0,0 +1,111 @@ +/* ---------------------------------------------------------------------- + LAMMPS - Large-scale Atomic/Molecular Massively Parallel Simulator + https://www.lammps.org/, Sandia National Laboratories + LAMMPS development team: developers@lammps.org + + Copyright (2003) Sandia Corporation. Under the terms of Contract + DE-AC04-94AL85000 with Sandia Corporation, the U.S. Government retains + certain rights in this software. This software is distributed under + the GNU General Public License. + + See the README file in the top-level LAMMPS directory. +------------------------------------------------------------------------- */ + +/* ---------------------------------------------------------------------- + Contributing authors: Axel Kohlmeyer (Temple U), +------------------------------------------------------------------------- */ + +#include "geturl.h" + +#include "comm.h" +#include "error.h" + +#if defined(LAMMPS_CURL) +#include +#endif + +using namespace LAMMPS_NS; + +/* ---------------------------------------------------------------------- */ + +void GetURL::command(int narg, char **arg) +{ +#if !defined(LAMMPS_CURL) + error->all(FLERR, "LAMMPS has not been compiled with libcurl support"); +#else + if (narg < 1) utils::missing_cmd_args(FLERR, "geturl", error); + int verify = 1; + int overwrite = 1; + + // process arguments + + std::string url = arg[0]; + + // sanity check + + if ((url.find(':') == std::string::npos) || (url.find('/') == std::string::npos)) + error->all(FLERR, "URL '{}' is not a supported URL", url); + + std::string output = url.substr(url.find_last_of('/') + 1); + if (output.empty()) error->all(FLERR, "URL '{}' must end in a file string", url); + + int iarg = 1; + while (iarg < narg) { + if (strcmp(arg[iarg], "output") == 0) { + if (iarg + 2 > narg) utils::missing_cmd_args(FLERR, "geturl output", error); + output = arg[iarg + 1]; + ++iarg; + } else if (strcmp(arg[iarg], "overwrite") == 0) { + if (iarg + 2 > narg) utils::missing_cmd_args(FLERR, "geturl overwrite", error); + overwrite = utils::logical(FLERR, arg[iarg + 1], false, lmp); + ++iarg; + } else if (strcmp(arg[iarg], "verify") == 0) { + if (iarg + 2 > narg) utils::missing_cmd_args(FLERR, "geturl verify", error); + verify = utils::logical(FLERR, arg[iarg + 1], false, lmp); + ++iarg; + } else { + error->all(FLERR, "Unknown geturl keyword: {}", arg[iarg]); + } + ++iarg; + } + + // only download files from rank 0 + + if (comm->me != 0) return; + + if (!overwrite && platform::file_is_readable(output)) return; + + // open output file for writing + + FILE *out = fopen(output.c_str(), "wb"); + if (!out) + error->all(FLERR, "Cannot open output file {} for writing: {}", output, utils::getsyserror()); + + // initialize curl and perform download + + CURL *curl; + curl_global_init(CURL_GLOBAL_DEFAULT); + curl = curl_easy_init(); + if (curl) { + curl_easy_setopt(curl, CURLOPT_URL, url.c_str()); + curl_easy_setopt(curl, CURLOPT_WRITEDATA, (void *) out); + curl_easy_setopt(curl, CURLOPT_FILETIME, 1L); + curl_easy_setopt(curl, CURLOPT_FAILONERROR, 1L); + + if (!verify) { + curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 0L); + curl_easy_setopt(curl, CURLOPT_SSL_VERIFYHOST, 0L); + } + auto res = curl_easy_perform(curl); + if (res != CURLE_OK) { + long response = 0L; + curl_easy_getinfo(curl, CURLINFO_RESPONSE_CODE, &response); + error->one(FLERR, "Download of {} failed with: {} {}", output, curl_easy_strerror(res), + response); + } + curl_easy_cleanup(curl); + } + curl_global_cleanup(); + fclose(out); +#endif +} diff --git a/src/EXTRA-COMMAND/geturl.h b/src/EXTRA-COMMAND/geturl.h new file mode 100644 index 0000000000..2f4cf8ccb3 --- /dev/null +++ b/src/EXTRA-COMMAND/geturl.h @@ -0,0 +1,34 @@ +/* -*- c++ -*- ---------------------------------------------------------- + LAMMPS - Large-scale Atomic/Molecular Massively Parallel Simulator + https://www.lammps.org/, Sandia National Laboratories + LAMMPS development team: developers@lammps.org + + Copyright (2003) Sandia Corporation. Under the terms of Contract + DE-AC04-94AL85000 with Sandia Corporation, the U.S. Government retains + certain rights in this software. This software is distributed under + the GNU General Public License. + + See the README file in the top-level LAMMPS directory. +------------------------------------------------------------------------- */ + +#ifdef COMMAND_CLASS +// clang-format off +CommandStyle(geturl,GetURL); +// clang-format on +#else + +#ifndef LMP_GETURL_H +#define LMP_GETURL_H + +#include "command.h" + +namespace LAMMPS_NS { + +class GetURL : public Command { + public: + GetURL(class LAMMPS *lmp) : Command(lmp) {}; + void command(int, char **) override; +}; +} // namespace LAMMPS_NS +#endif +#endif From 3fa48dfa345432d5109ba922f8c79a3e7c18b699 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Wed, 7 Aug 2024 09:37:33 -0400 Subject: [PATCH 02/15] build system integration of geturl --- cmake/CMakeLists.txt | 8 +++++++ src/.gitignore | 2 ++ src/MAKE/Makefile.mpi | 35 ++++++++++++++++++---------- src/MAKE/Makefile.serial | 49 ++++++++++++++++++++++++---------------- 4 files changed, 63 insertions(+), 31 deletions(-) diff --git a/cmake/CMakeLists.txt b/cmake/CMakeLists.txt index eac2cc87c2..5b29fb6047 100644 --- a/cmake/CMakeLists.txt +++ b/cmake/CMakeLists.txt @@ -510,6 +510,14 @@ if(PKG_ATC OR PKG_AWPMD OR PKG_ML-QUIP OR PKG_ML-POD OR PKG_ELECTRODE OR BUILD_T endif() endif() +find_package(CURL QUIET COMPONENTS HTTP HTTPS) +option(WITH_CURL "Enable libcurl support" ${CURL_FOUND}) +if(WITH_CURL) + find_package(CURL REQUIRED COMPONENTS HTTP HTTPS) + target_compile_definitions(lammps PRIVATE -DLAMMPS_CURL) + target_link_libraries(lammps PRIVATE CURL::libcurl) +endif() + # tweak jpeg library names to avoid linker errors with MinGW cross-compilation set(JPEG_NAMES libjpeg libjpeg-62) find_package(JPEG QUIET) diff --git a/src/.gitignore b/src/.gitignore index 5b13a7d55a..c26eaaba30 100644 --- a/src/.gitignore +++ b/src/.gitignore @@ -1075,6 +1075,8 @@ /fix_wall_srd.h /fix_widom.cpp /fix_widom.h +/geturl.cpp +/geturl.h /gpu_extra.h /group_ndx.cpp /group_ndx.h diff --git a/src/MAKE/Makefile.mpi b/src/MAKE/Makefile.mpi index 933da9663e..9cd451a32c 100644 --- a/src/MAKE/Makefile.mpi +++ b/src/MAKE/Makefile.mpi @@ -35,9 +35,9 @@ LMP_INC = -DLAMMPS_GZIP -DLAMMPS_MEMALIGN=64 # -DLAMMPS_CXX98 # MPI wrapper compiler/linker can provide this info # can point to dummy MPI library in src/STUBS as in Makefile.serial # use -D MPICH and OMPI settings in INC to avoid C++ lib conflicts -# INC = path for mpi.h, MPI compiler settings -# PATH = path for MPI library -# LIB = name of MPI library +# MPI_INC = path for mpi.h, MPI compiler settings +# MPI_PATH = path for MPI library +# MPI_LIB = name of MPI library MPI_INC = -DMPICH_SKIP_MPICXX -DOMPI_SKIP_MPICXX=1 MPI_PATH = @@ -46,9 +46,9 @@ MPI_LIB = # FFT library # see discussion in Section 3.5.2 of manual # can be left blank to use provided KISS FFT library -# INC = -DFFT setting, e.g. -DFFT_FFTW, FFT compiler settings -# PATH = path for FFT library -# LIB = name of FFT library +# FFT_INC = -DFFT setting, e.g. -DFFT_FFTW, FFT compiler settings +# FFT_PATH = path for FFT library +# FFT_LIB = name of FFT library FFT_INC = FFT_PATH = @@ -57,14 +57,25 @@ FFT_LIB = # JPEG and/or PNG library # see discussion in Section 3.5.4 of manual # only needed if -DLAMMPS_JPEG or -DLAMMPS_PNG listed with LMP_INC -# INC = path(s) for jpeglib.h and/or png.h -# PATH = path(s) for JPEG library and/or PNG library -# LIB = name(s) of JPEG library and/or PNG library +# JPG_INC = path(s) for jpeglib.h and/or png.h +# JPG_PATH = path(s) for JPEG library and/or PNG library +# JPG_LIB = name(s) of JPEG library and/or PNG library JPG_INC = JPG_PATH = JPG_LIB = +# CURL library +# see discussion in Section 3.5.6 of manual +# only needed if -DLAMMPS_CURL listed with LMP_INC +# CURL_INC = path(s) for curl/curl.h +# CURL_PATH = path(s) for CURL library +# CURL_LIB = name(s) of CURL library, e.g. -lcurl + +CURL_INC = +CURL_PATH = +CURL_LIB = + # library for loading shared objects (defaults to -ldl, should be empty on Windows) # uncomment to change the default @@ -77,9 +88,9 @@ JPG_LIB = include Makefile.package.settings include Makefile.package -EXTRA_INC = $(LMP_INC) $(PKG_INC) $(MPI_INC) $(FFT_INC) $(JPG_INC) $(PKG_SYSINC) -EXTRA_PATH = $(PKG_PATH) $(MPI_PATH) $(FFT_PATH) $(JPG_PATH) $(PKG_SYSPATH) -EXTRA_LIB = $(PKG_LIB) $(MPI_LIB) $(FFT_LIB) $(JPG_LIB) $(PKG_SYSLIB) $(DYN_LIB) +EXTRA_INC = $(LMP_INC) $(PKG_INC) $(MPI_INC) $(FFT_INC) $(JPG_INC) $(CURL_INC) $(PKG_SYSINC) +EXTRA_PATH = $(PKG_PATH) $(MPI_PATH) $(FFT_PATH) $(JPG_PATH) $(CURL_PATH) $(PKG_SYSPATH) +EXTRA_LIB = $(PKG_LIB) $(MPI_LIB) $(FFT_LIB) $(JPG_LIB) $(CURL_LIB) $(PKG_SYSLIB) $(DYN_LIB) EXTRA_CPP_DEPENDS = $(PKG_CPP_DEPENDS) EXTRA_LINK_DEPENDS = $(PKG_LINK_DEPENDS) diff --git a/src/MAKE/Makefile.serial b/src/MAKE/Makefile.serial index 6dd8415ea9..f588922a1f 100644 --- a/src/MAKE/Makefile.serial +++ b/src/MAKE/Makefile.serial @@ -35,35 +35,46 @@ LMP_INC = -DLAMMPS_GZIP -DLAMMPS_MEMALIGN=64 # -DLAMMPS_CXX98 # MPI wrapper compiler/linker can provide this info # can point to dummy MPI library in src/STUBS as in Makefile.serial # use -D MPICH and OMPI settings in INC to avoid C++ lib conflicts -# INC = path for mpi.h, MPI compiler settings -# PATH = path for MPI library -# LIB = name of MPI library +# MPI_INC = path for mpi.h, MPI compiler settings +# MPI_PATH = path for MPI library +# MPI_LIB = name of MPI library -MPI_INC = -I../STUBS +MPI_INC = -I../STUBS MPI_PATH = -L../STUBS MPI_LIB = -lmpi_stubs # FFT library # see discussion in Section 3.5.2 of manual # can be left blank to use provided KISS FFT library -# INC = -DFFT setting, e.g. -DFFT_FFTW, FFT compiler settings -# PATH = path for FFT library -# LIB = name of FFT library +# FFT_INC = -DFFT setting, e.g. -DFFT_FFTW, FFT compiler settings +# FFT_PATH = path for FFT library +# FFT_LIB = name of FFT library -FFT_INC = -FFT_PATH = -FFT_LIB = +FFT_INC = +FFT_PATH = +FFT_LIB = # JPEG and/or PNG library # see discussion in Section 3.5.4 of manual # only needed if -DLAMMPS_JPEG or -DLAMMPS_PNG listed with LMP_INC -# INC = path(s) for jpeglib.h and/or png.h -# PATH = path(s) for JPEG library and/or PNG library -# LIB = name(s) of JPEG library and/or PNG library +# JPG_INC = path(s) for jpeglib.h and/or png.h +# JPG_PATH = path(s) for JPEG library and/or PNG library +# JPG_LIB = name(s) of JPEG library and/or PNG library -JPG_INC = -JPG_PATH = -JPG_LIB = +JPG_INC = +JPG_PATH = +JPG_LIB = + +# CURL library +# see discussion in Section 3.5.6 of manual +# only needed if -DLAMMPS_CURL listed with LMP_INC +# CURL_INC = path(s) for curl/curl.h +# CURL_PATH = path(s) for CURL library +# CURL_LIB = name(s) of CURL library, e.g. -lcurl + +CURL_INC = +CURL_PATH = +CURL_LIB = # library for loading shared objects (defaults to -ldl, should be empty on Windows) # uncomment to change the default @@ -77,9 +88,9 @@ JPG_LIB = include Makefile.package.settings include Makefile.package -EXTRA_INC = $(LMP_INC) $(PKG_INC) $(MPI_INC) $(FFT_INC) $(JPG_INC) $(PKG_SYSINC) -EXTRA_PATH = $(PKG_PATH) $(MPI_PATH) $(FFT_PATH) $(JPG_PATH) $(PKG_SYSPATH) -EXTRA_LIB = $(PKG_LIB) $(MPI_LIB) $(FFT_LIB) $(JPG_LIB) $(PKG_SYSLIB) $(DYN_LIB) +EXTRA_INC = $(LMP_INC) $(PKG_INC) $(MPI_INC) $(FFT_INC) $(JPG_INC) $(CURL_INC) $(PKG_SYSINC) +EXTRA_PATH = $(PKG_PATH) $(MPI_PATH) $(FFT_PATH) $(JPG_PATH) $(CURL_PATH) $(PKG_SYSPATH) +EXTRA_LIB = $(PKG_LIB) $(MPI_LIB) $(FFT_LIB) $(JPG_LIB) $(CURL_LIB) $(PKG_SYSLIB) $(DYN_LIB) EXTRA_CPP_DEPENDS = $(PKG_CPP_DEPENDS) EXTRA_LINK_DEPENDS = $(PKG_LINK_DEPENDS) From dcb3871e58065f959f1d47f593bd10da6bd6ad82 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Wed, 7 Aug 2024 09:37:49 -0400 Subject: [PATCH 03/15] doc integration of gerurl --- doc/src/Build_settings.rst | 65 ++++++++++++++++++--- doc/src/Commands_all.rst | 1 + doc/src/commands_list.rst | 1 + doc/utils/sphinx-config/false_positives.txt | 6 ++ 4 files changed, 65 insertions(+), 8 deletions(-) diff --git a/doc/src/Build_settings.rst b/doc/src/Build_settings.rst index b6aa6e4114..cefadc183e 100644 --- a/doc/src/Build_settings.rst +++ b/doc/src/Build_settings.rst @@ -8,7 +8,8 @@ explains how to do this for building both with CMake and make. * `FFT library`_ for use with the :doc:`kspace_style pppm ` command * `Size of LAMMPS integer types and size limits`_ * `Read or write compressed files`_ -* `Output of JPG, PNG, and move files` via the :doc:`dump image ` or :doc:`dump movie ` commands +* `Output of JPEG, PNG, and movie files`_ via the :doc:`dump image ` or :doc:`dump movie ` commands +* `Support for downloading files`_ * `Memory allocation alignment`_ * `Workaround for long long integers`_ * `Exception handling when using LAMMPS as a library`_ to capture errors @@ -19,7 +20,7 @@ explains how to do this for building both with CMake and make. .. _cxx11: C++11 standard compliance ------------------------------------------- +------------------------- A C++11 standard compatible compiler is a requirement for compiling LAMMPS. LAMMPS version 3 March 2020 is the last version compatible with the previous @@ -31,12 +32,16 @@ flags to enable C++11 compliance. Example for GNU c++ 4.8.x: CCFLAGS = -g -O3 -std=c++11 +Individual packages may require compliance with a later C++ standard +like C++14 or C++17. These requirements will be documented with the +:doc:`individual packages `. + ---------- .. _fft: FFT library ---------------------- +----------- When the KSPACE package is included in a LAMMPS build, the :doc:`kspace_style pppm ` command performs 3d FFTs which @@ -341,8 +346,8 @@ in whichever ``lib/gpu/Makefile`` is used must be the same as above. .. _graphics: -Output of JPG, PNG, and movie files --------------------------------------------------- +Output of JPEG, PNG, and movie files +------------------------------------ The :doc:`dump image ` command has options to output JPEG or PNG image files. Likewise, the :doc:`dump movie ` command @@ -356,9 +361,9 @@ requires the following settings: .. code-block:: bash -D WITH_JPEG=value # yes or no - # default = yes if CMake finds JPEG files, else no + # default = yes if CMake finds JPEG development files, else no -D WITH_PNG=value # yes or no - # default = yes if CMake finds PNG and ZLIB files, else no + # default = yes if CMake finds PNG and ZLIB development files, else no -D WITH_FFMPEG=value # yes or no # default = yes if CMake can find ffmpeg, else no @@ -446,12 +451,56 @@ during a run. available using a compression library instead, which is what the :ref:`COMPRESS package ` enables. +-------------------------------------------------- + +.. _libcurl: + +Support for downloading files +----------------------------- + +The :doc:`geturl command ` command uses the `the libcurl library +`_ to download files. This requires that +LAMMPS is compiled accordingly which needs the following settings: + +.. tabs:: + + .. tab:: CMake build + + .. code-block:: bash + + -D WITH_CURL=value # yes or no + # default = yes if CMake finds CURL development files, else no + + Usually these settings are all that is needed. If CMake cannot + find the graphics header, library, executable files, you can set + these variables: + + .. code-block:: bash + + -D CURL_INCLUDE_DIR=path # path to folder which contains curl.h header file + -D CURL_LIBRARY=path # path to libcurls.a (.so) file + + .. tab:: Traditional make + + .. code-block:: make + + LMP_INC = -DLAMMPS_CURL + + CURL_INC = -I/usr/local/include # path to curl folder with curl.h + CURL_PATH = -L/usr/lib # paths to libcurl.a(.so) if make cannot find it + CURL_LIB = -lcurl # library names + + As with CMake, you do not need to set ``CURL_INC`` or ``CURL_PATH``, + if make can find the libcurl header and library files in their + default system locations. You must specify ``CURL_LIB`` with a + paths or linker flags to link to libcurl. + ---------- .. _align: Memory allocation alignment ---------------------------------------- +--------------------------- This setting enables the use of the "posix_memalign()" call instead of "malloc()" when LAMMPS allocates large chunks of memory. Vector diff --git a/doc/src/Commands_all.rst b/doc/src/Commands_all.rst index 4a035f5b41..cb31369501 100644 --- a/doc/src/Commands_all.rst +++ b/doc/src/Commands_all.rst @@ -54,6 +54,7 @@ table above. * :doc:`echo ` * :doc:`fix ` * :doc:`fix_modify ` + * :doc:`geturl ` * :doc:`group ` * :doc:`if ` * :doc:`improper_coeff ` diff --git a/doc/src/commands_list.rst b/doc/src/commands_list.rst index cea237f14e..b297b6dbf5 100644 --- a/doc/src/commands_list.rst +++ b/doc/src/commands_list.rst @@ -45,6 +45,7 @@ Commands fix fix_modify fitpod_command + geturl group group2ndx hyper diff --git a/doc/utils/sphinx-config/false_positives.txt b/doc/utils/sphinx-config/false_positives.txt index 5406c3ac79..f6db58ecd9 100644 --- a/doc/utils/sphinx-config/false_positives.txt +++ b/doc/utils/sphinx-config/false_positives.txt @@ -1298,6 +1298,7 @@ Gershgorin getrusage getter gettimeofday +geturl gewald Gezelter Gflop @@ -1492,6 +1493,8 @@ hplanck Hs hstyle html +http +https hTST https hu @@ -3349,6 +3352,7 @@ Schunk Schuring Schwen Sci +scp screenshot screenshots Scripps @@ -3389,6 +3393,7 @@ setvel sevenbody sfftw sfree +sftp Sg sgcmc Shan @@ -3903,6 +3908,7 @@ upenn upto Urbakh Urbana +url UreyBradley Usabiaga usec From fe9c9cc77d2b76d0044dfb74db5206d4f1ba84cf Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Wed, 7 Aug 2024 09:38:10 -0400 Subject: [PATCH 04/15] fix highlighting bug and add geturl --- tools/lammps-gui/highlighter.cpp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tools/lammps-gui/highlighter.cpp b/tools/lammps-gui/highlighter.cpp index d6c1102285..3f79c7a73e 100644 --- a/tools/lammps-gui/highlighter.cpp +++ b/tools/lammps-gui/highlighter.cpp @@ -23,7 +23,7 @@ Highlighter::Highlighter(QTextDocument *parent) : "thermo|print|thermo_style|" "timer|pair_write|bond_write|angle_write|dihedral_write)\\s+(\\S+)")), isOutput2(QStringLiteral("^\\s*(write_dump|shell|thermo_modify)\\s+(\\S+)\\s+(\\S+)")), - isRead(QStringLiteral("^\\s*(include|read_restart|read_data|read_dump|molecule)")), + isRead(QStringLiteral("^\\s*(include|read_restart|read_data|read_dump|molecule|geturl)\\s+(\\S+)")), isStyle(QStringLiteral("^\\s*(fix|compute|dump)\\s+(\\S+)\\s+(\\S+)\\s+(\\S+)")), isForce(QStringLiteral( "^\\s*(pair_style|bond_style|angle_style|dihedral_style|improper_style|kspace_style|pair_" From 85f322e4f2d142b736823b436b0a782891a6ca1f Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Wed, 7 Aug 2024 10:27:19 -0400 Subject: [PATCH 05/15] add introspection support for -DLAMMPS_CURL --- src/info.cpp | 11 +++++++++++ src/info.h | 3 ++- 2 files changed, 13 insertions(+), 1 deletion(-) diff --git a/src/info.cpp b/src/info.cpp index 43409fca67..6c0607f0fb 100644 --- a/src/info.cpp +++ b/src/info.cpp @@ -296,6 +296,7 @@ void Info::command(int narg, char **arg) if (has_png_support()) fputs("-DLAMMPS_PNG\n",out); if (has_jpeg_support()) fputs("-DLAMMPS_JPEG\n",out); if (has_ffmpeg_support()) fputs("-DLAMMPS_FFMPEG\n",out); + if (has_curl_support()) fputs("-DLAMMPS_CURL\n",out); if (has_fft_single_support()) fputs("-DFFT_SINGLE\n",out); #if defined(LAMMPS_BIGBIG) @@ -857,6 +858,8 @@ bool Info::is_available(const char *category, const char *name) return has_jpeg_support(); } else if (strcmp(name,"ffmpeg") == 0) { return has_ffmpeg_support(); + } else if (strcmp(name,"curl") == 0) { + return has_curl_support(); } else if (strcmp(name,"fft_single") == 0) { return has_fft_single_support(); } else if (strcmp(name,"exceptions") == 0) { @@ -1077,6 +1080,14 @@ bool Info::has_ffmpeg_support() { #endif } +bool Info::has_curl_support() { +#ifdef LAMMPS_CURL + return true; +#else + return false; +#endif +} + bool Info::has_fft_single_support() { #ifdef FFT_SINGLE return true; diff --git a/src/info.h b/src/info.h index 8fd725abf6..12c19eb877 100644 --- a/src/info.h +++ b/src/info.h @@ -28,7 +28,7 @@ namespace LAMMPS_NS { class Info : public Command { public: - Info(class LAMMPS *lmp) : Command(lmp){}; + Info(class LAMMPS *lmp) : Command(lmp) {}; void command(int, char **) override; bool is_active(const char *, const char *); @@ -42,6 +42,7 @@ class Info : public Command { static bool has_png_support(); static bool has_jpeg_support(); static bool has_ffmpeg_support(); + static bool has_curl_support(); static bool has_fft_single_support(); static bool has_exceptions(); static bool has_package(const std::string &); From 937c17f3b88a775857cec269f8d3c9faf9e94227 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Wed, 7 Aug 2024 10:27:48 -0400 Subject: [PATCH 06/15] add tests for geturl command --- unittest/commands/test_simple_commands.cpp | 51 ++++++++++++++++++++-- 1 file changed, 48 insertions(+), 3 deletions(-) diff --git a/unittest/commands/test_simple_commands.cpp b/unittest/commands/test_simple_commands.cpp index 79ea1c71ce..d3fef447ac 100644 --- a/unittest/commands/test_simple_commands.cpp +++ b/unittest/commands/test_simple_commands.cpp @@ -19,6 +19,7 @@ #include "info.h" #include "input.h" #include "output.h" +#include "platform.h" #include "update.h" #include "utils.h" #include "variable.h" @@ -214,9 +215,9 @@ TEST_F(SimpleCommandsTest, Quit) TEST_FAILURE(".*ERROR: Expected integer .*", command("quit xxx");); // the following tests must be skipped with OpenMPI or MPICH 4.1 and later due to using threads - if (platform::mpi_vendor() == "Open MPI") GTEST_SKIP(); + if (platform::mpi_vendor() == "Open MPI") GTEST_SKIP() << "OpenMPI"; #if defined(MPICH_NUMVERSION) - if (MPICH_NUMVERSION >= 40100000) GTEST_SKIP(); + if (MPICH_NUMVERSION >= 40100000) GTEST_SKIP() << "MPICH with threads"; #endif ASSERT_EXIT(command("quit"), ExitedWithCode(0), ""); ASSERT_EXIT(command("quit 9"), ExitedWithCode(9), ""); @@ -412,7 +413,7 @@ TEST_F(SimpleCommandsTest, Plugin) { const char *bindir = getenv("LAMMPS_PLUGIN_BIN_DIR"); const char *config = getenv("CMAKE_CONFIG_TYPE"); - if (!bindir) GTEST_SKIP(); + if (!bindir) GTEST_SKIP() << "LAMMPS_PLUGIN_BIN_DIR not set"; std::string loadfmt = platform::path_join("plugin load ", bindir); if (config) loadfmt = platform::path_join(loadfmt, config); loadfmt = platform::path_join(loadfmt, "{}plugin.so"); @@ -556,6 +557,50 @@ TEST_F(SimpleCommandsTest, CiteMe) // no new citation. no CITE-CITE-CITE- lines ASSERT_THAT(text, Not(ContainsRegex(".*CITE-CITE-CITE-CITE.*"))); } + +TEST_F(SimpleCommandsTest, Geturl) +{ + if (!LAMMPS::is_installed_pkg("EXTRA-COMMAND")) GTEST_SKIP(); + platform::unlink("index.html"); + platform::unlink("myindex.html"); + if (Info::has_curl_support()) { + BEGIN_CAPTURE_OUTPUT(); + command("geturl https://www.lammps.org/index.html"); + command("geturl https://www.lammps.org/index.html output myindex.html"); + END_CAPTURE_OUTPUT(); + EXPECT_TRUE(platform::file_is_readable("index.html")); + EXPECT_TRUE(platform::file_is_readable("myindex.html")); + FILE *fp = fopen("index.html", "wb"); + fputs("just testing\n", fp); + fclose(fp); + BEGIN_CAPTURE_OUTPUT(); + command("geturl https://www.lammps.org/index.html overwrite no"); + END_CAPTURE_OUTPUT(); + char checkme[20]; + fp = fopen("index.html", "rb"); + fgets(checkme, 19, fp); + fclose(fp); + EXPECT_EQ(strcmp(checkme, "just testing\n"), 0); + BEGIN_CAPTURE_OUTPUT(); + command("geturl https://www.lammps.org/index.html overwrite yes"); + END_CAPTURE_OUTPUT(); + fp = fopen("index.html", "rb"); + fgets(checkme, 19, fp); + fclose(fp); + EXPECT_NE(strcmp(checkme, "just testing\n"), 0); + TEST_FAILURE(".*ERROR: Illegal geturl command: missing argument.*", command("geturl ");); + TEST_FAILURE(".*ERROR: URL 'dummy' is not a supported URL.*", command("geturl dummy");); + TEST_FAILURE(".*ERROR on proc 0: Download of xxx.txt failed with: " + "HTTP response code said error 404.*", + command("geturl https://www.lammps.org/xxx.txt");); + } else { + TEST_FAILURE(".*ERROR: LAMMPS has not been compiled with libcurl support*", + command("geturl https:://www.lammps.org/index.html");); + } + platform::unlink("index.html"); + platform::unlink("myindex.html"); +} + } // namespace LAMMPS_NS int main(int argc, char **argv) From f197ce31650f6b68098a967b6be0b37c510cb2d9 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Wed, 7 Aug 2024 10:37:20 -0400 Subject: [PATCH 07/15] expose new introspection to library interfaces for consistency --- examples/COUPLE/plugin/liblammpsplugin.c | 1 + examples/COUPLE/plugin/liblammpsplugin.h | 1 + fortran/lammps.f90 | 15 +++++++++++++++ python/lammps/core.py | 15 +++++++++++++++ src/library.cpp | 17 +++++++++++++++++ src/library.h | 1 + tools/swig/lammps.i | 2 ++ 7 files changed, 52 insertions(+) diff --git a/examples/COUPLE/plugin/liblammpsplugin.c b/examples/COUPLE/plugin/liblammpsplugin.c index 7df23c5b67..5d27a0a64b 100644 --- a/examples/COUPLE/plugin/liblammpsplugin.c +++ b/examples/COUPLE/plugin/liblammpsplugin.c @@ -150,6 +150,7 @@ liblammpsplugin_t *liblammpsplugin_load(const char *lib) ADDSYM(config_has_png_support); ADDSYM(config_has_jpeg_support); ADDSYM(config_has_ffmpeg_support); + ADDSYM(config_has_curl_support); ADDSYM(config_has_exceptions); ADDSYM(config_has_package); diff --git a/examples/COUPLE/plugin/liblammpsplugin.h b/examples/COUPLE/plugin/liblammpsplugin.h index 9f53e4749b..556718816c 100644 --- a/examples/COUPLE/plugin/liblammpsplugin.h +++ b/examples/COUPLE/plugin/liblammpsplugin.h @@ -203,6 +203,7 @@ struct _liblammpsplugin { int (*config_has_png_support)(); int (*config_has_jpeg_support)(); int (*config_has_ffmpeg_support)(); + int (*config_has_curl_support)(); int (*config_has_exceptions)(); int (*config_has_package)(const char *); diff --git a/fortran/lammps.f90 b/fortran/lammps.f90 index a70a7e8af4..1617891b92 100644 --- a/fortran/lammps.f90 +++ b/fortran/lammps.f90 @@ -196,6 +196,7 @@ MODULE LIBLAMMPS PROCEDURE, NOPASS :: config_has_jpeg_support => lmp_config_has_jpeg_support PROCEDURE, NOPASS :: config_has_ffmpeg_support & => lmp_config_has_ffmpeg_support + PROCEDURE, NOPASS :: config_has_curl_support => lmp_config_has_curl_support PROCEDURE, NOPASS :: config_has_exceptions => lmp_config_has_exceptions PROCEDURE, NOPASS :: config_has_package => lmp_config_has_package PROCEDURE, NOPASS :: config_package_count => lammps_config_package_count @@ -793,6 +794,12 @@ MODULE LIBLAMMPS INTEGER(c_int) :: lammps_config_has_ffmpeg_support END FUNCTION lammps_config_has_ffmpeg_support + FUNCTION lammps_config_has_curl_support() BIND(C) + IMPORT :: c_int + IMPLICIT NONE + INTEGER(c_int) :: lammps_config_has_curl_support + END FUNCTION lammps_config_has_curl_support + FUNCTION lammps_config_has_exceptions() BIND(C) IMPORT :: c_int IMPLICIT NONE @@ -2881,6 +2888,14 @@ CONTAINS lmp_config_has_ffmpeg_support = (has_ffmpeg_support /= 0_c_int) END FUNCTION lmp_config_has_ffmpeg_support + ! equivalent function to lammps_config_has_curl_support + LOGICAL FUNCTION lmp_config_has_curl_support() + INTEGER(c_int) :: has_curl_support + + has_curl_support = lammps_config_has_curl_support() + lmp_config_has_curl_support = (has_curl_support /= 0_c_int) + END FUNCTION lmp_config_has_curl_support + ! equivalent function to lammps_config_has_exceptions LOGICAL FUNCTION lmp_config_has_exceptions() INTEGER(c_int) :: has_exceptions diff --git a/python/lammps/core.py b/python/lammps/core.py index 42e8652fef..9080dd9c56 100644 --- a/python/lammps/core.py +++ b/python/lammps/core.py @@ -1969,6 +1969,21 @@ class lammps(object): # ------------------------------------------------------------------------- + @property + def has_curl_support(self): + """ Report whether the LAMMPS shared library was compiled with support + for downloading files through libcurl. + + This is a wrapper around the :cpp:func:`lammps_config_has_curl_support` + function of the library interface. + + :return: state of CURL support + :rtype: bool + """ + return self.lib.lammps_config_has_curl_support() != 0 + + # ------------------------------------------------------------------------- + def has_package(self, name): """ Report if the named package has been enabled in the LAMMPS shared library. diff --git a/src/library.cpp b/src/library.cpp index b7a2113de8..549a015767 100644 --- a/src/library.cpp +++ b/src/library.cpp @@ -5877,6 +5877,23 @@ int lammps_config_has_ffmpeg_support() { /* ---------------------------------------------------------------------- */ +/** Check if the LAMMPS library supports downloading files via libcurl + +\verbatim embed:rst +The LAMMPS :doc:`geturl command ` supports downloading files +through using `the libcurl library `_. +This function checks whether this feature was :ref:`enabled at compile +time ` and LAMMPS linked to the libcurl library. +\endverbatim + * + * \return 1 if yes, otherwise 0 + */ +int lammps_config_has_curl_support() { + return Info::has_curl_support() ? 1 : 0; +} + +/* ---------------------------------------------------------------------- */ + /** Check whether LAMMPS errors will throw C++ exceptions. * \verbatim embed:rst diff --git a/src/library.h b/src/library.h index 38ecffb772..ff16aaa088 100644 --- a/src/library.h +++ b/src/library.h @@ -243,6 +243,7 @@ int lammps_config_has_gzip_support(); int lammps_config_has_png_support(); int lammps_config_has_jpeg_support(); int lammps_config_has_ffmpeg_support(); +int lammps_config_has_curl_support(); int lammps_config_has_exceptions(); int lammps_config_has_package(const char *); diff --git a/tools/swig/lammps.i b/tools/swig/lammps.i index 2207a72e36..9bef047da4 100644 --- a/tools/swig/lammps.i +++ b/tools/swig/lammps.i @@ -171,6 +171,7 @@ extern int lammps_config_has_gzip_support(); extern int lammps_config_has_png_support(); extern int lammps_config_has_jpeg_support(); extern int lammps_config_has_ffmpeg_support(); +extern int lammps_config_has_curl_support(); extern int lammps_config_has_exceptions(); extern int lammps_config_has_package(const char *); extern int lammps_config_package_count(); @@ -359,6 +360,7 @@ extern int lammps_config_has_gzip_support(); extern int lammps_config_has_png_support(); extern int lammps_config_has_jpeg_support(); extern int lammps_config_has_ffmpeg_support(); +extern int lammps_config_has_curl_support(); extern int lammps_config_has_exceptions(); extern int lammps_config_has_package(const char *); extern int lammps_config_package_count(); From c47a32206ba7c01fca6a8e2b79631036515a0a5e Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Wed, 7 Aug 2024 10:47:58 -0400 Subject: [PATCH 08/15] add versionadded tags --- doc/src/Build_settings.rst | 2 ++ doc/src/geturl.rst | 2 ++ src/library.cpp | 3 +++ 3 files changed, 7 insertions(+) diff --git a/doc/src/Build_settings.rst b/doc/src/Build_settings.rst index cefadc183e..2abe6c4678 100644 --- a/doc/src/Build_settings.rst +++ b/doc/src/Build_settings.rst @@ -458,6 +458,8 @@ during a run. Support for downloading files ----------------------------- +.. versionadded:: TBD + The :doc:`geturl command ` command uses the `the libcurl library `_ to download files. This requires that LAMMPS is compiled accordingly which needs the following settings: diff --git a/doc/src/geturl.rst b/doc/src/geturl.rst index e75e5cd1bf..5d033c43a3 100644 --- a/doc/src/geturl.rst +++ b/doc/src/geturl.rst @@ -31,6 +31,8 @@ Examples Description """"""""""" +.. versionadded:: TBD + Download a file from an URL to the local disk. This is implemented with the `libcurl library `_ which supports a large variety of protocols including "http", "https", "ftp", "scp", diff --git a/src/library.cpp b/src/library.cpp index 549a015767..9f77dad1c2 100644 --- a/src/library.cpp +++ b/src/library.cpp @@ -5880,6 +5880,9 @@ int lammps_config_has_ffmpeg_support() { /** Check if the LAMMPS library supports downloading files via libcurl \verbatim embed:rst + +.. versionadded::TBD + The LAMMPS :doc:`geturl command ` supports downloading files through using `the libcurl library `_. This function checks whether this feature was :ref:`enabled at compile From a8bb296a17c71b9b68d2356d88ed2e6fc921c49a Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Wed, 7 Aug 2024 11:15:13 -0400 Subject: [PATCH 09/15] switch to verbose mode to debug GitHub runner. --- unittest/commands/test_simple_commands.cpp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/unittest/commands/test_simple_commands.cpp b/unittest/commands/test_simple_commands.cpp index d3fef447ac..e8a1aab23f 100644 --- a/unittest/commands/test_simple_commands.cpp +++ b/unittest/commands/test_simple_commands.cpp @@ -36,7 +36,7 @@ #include // whether to print verbose output (i.e. not capturing LAMMPS screen output). -bool verbose = false; +bool verbose = true; namespace LAMMPS_NS { using ::testing::ContainsRegex; From cdab8d09ad85a85bec7e435261fff486002814c6 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Wed, 7 Aug 2024 12:12:45 -0400 Subject: [PATCH 10/15] need to update LAMMPS help message, too --- src/lammps.cpp | 1 + 1 file changed, 1 insertion(+) diff --git a/src/lammps.cpp b/src/lammps.cpp index 8e81f785de..7e73fd17f5 100644 --- a/src/lammps.cpp +++ b/src/lammps.cpp @@ -1454,6 +1454,7 @@ void LAMMPS::print_config(FILE *fp) if (Info::has_png_support()) fputs("-DLAMMPS_PNG\n",fp); if (Info::has_jpeg_support()) fputs("-DLAMMPS_JPEG\n",fp); if (Info::has_ffmpeg_support()) fputs("-DLAMMPS_FFMPEG\n",fp); + if (Info::has_curl_support()) fputs("-DLAMMPS_CURL\n",fp); if (Info::has_fft_single_support()) fputs("-DFFT_SINGLE\n",fp); #if defined(LAMMPS_BIGBIG) fputs("-DLAMMPS_BIGBIG\n",fp); From c8ba358f67183a7e6ad1c7bb72f306e642b658c4 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Wed, 7 Aug 2024 12:20:35 -0400 Subject: [PATCH 11/15] more debugging github runner for macos --- unittest/commands/test_simple_commands.cpp | 1 + 1 file changed, 1 insertion(+) diff --git a/unittest/commands/test_simple_commands.cpp b/unittest/commands/test_simple_commands.cpp index e8a1aab23f..017d7ee870 100644 --- a/unittest/commands/test_simple_commands.cpp +++ b/unittest/commands/test_simple_commands.cpp @@ -565,6 +565,7 @@ TEST_F(SimpleCommandsTest, Geturl) platform::unlink("myindex.html"); if (Info::has_curl_support()) { BEGIN_CAPTURE_OUTPUT(); + command("shell curl -v -o myindex.html https://www.lammps.org/index.html"); command("geturl https://www.lammps.org/index.html"); command("geturl https://www.lammps.org/index.html output myindex.html"); END_CAPTURE_OUTPUT(); From af6805198141e22fa792676d95d3ddf9c64ee4b0 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Wed, 7 Aug 2024 12:41:32 -0400 Subject: [PATCH 12/15] switch libcur to verbose output --- src/EXTRA-COMMAND/geturl.cpp | 1 + 1 file changed, 1 insertion(+) diff --git a/src/EXTRA-COMMAND/geturl.cpp b/src/EXTRA-COMMAND/geturl.cpp index df46d0b723..3350b18455 100644 --- a/src/EXTRA-COMMAND/geturl.cpp +++ b/src/EXTRA-COMMAND/geturl.cpp @@ -91,6 +91,7 @@ void GetURL::command(int narg, char **arg) curl_easy_setopt(curl, CURLOPT_WRITEDATA, (void *) out); curl_easy_setopt(curl, CURLOPT_FILETIME, 1L); curl_easy_setopt(curl, CURLOPT_FAILONERROR, 1L); + curl_easy_setopt(curl, CURLOPT_VERBOSE, 1L); if (!verify) { curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 0L); From 69294ef3439774ea581a0c5028c610576f61da5b Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Wed, 7 Aug 2024 13:08:35 -0400 Subject: [PATCH 13/15] add "verbose" option for debugging which will divert libcurl logging to the screen --- src/EXTRA-COMMAND/geturl.cpp | 11 +++++++++-- unittest/commands/test_simple_commands.cpp | 3 +-- 2 files changed, 10 insertions(+), 4 deletions(-) diff --git a/src/EXTRA-COMMAND/geturl.cpp b/src/EXTRA-COMMAND/geturl.cpp index 3350b18455..106abb19d4 100644 --- a/src/EXTRA-COMMAND/geturl.cpp +++ b/src/EXTRA-COMMAND/geturl.cpp @@ -36,6 +36,7 @@ void GetURL::command(int narg, char **arg) if (narg < 1) utils::missing_cmd_args(FLERR, "geturl", error); int verify = 1; int overwrite = 1; + int verbose = 0; // process arguments @@ -63,6 +64,10 @@ void GetURL::command(int narg, char **arg) if (iarg + 2 > narg) utils::missing_cmd_args(FLERR, "geturl verify", error); verify = utils::logical(FLERR, arg[iarg + 1], false, lmp); ++iarg; + } else if (strcmp(arg[iarg], "verbose") == 0) { + if (iarg + 2 > narg) utils::missing_cmd_args(FLERR, "geturl verbose", error); + verbose = utils::logical(FLERR, arg[iarg + 1], false, lmp); + ++iarg; } else { error->all(FLERR, "Unknown geturl keyword: {}", arg[iarg]); } @@ -91,8 +96,10 @@ void GetURL::command(int narg, char **arg) curl_easy_setopt(curl, CURLOPT_WRITEDATA, (void *) out); curl_easy_setopt(curl, CURLOPT_FILETIME, 1L); curl_easy_setopt(curl, CURLOPT_FAILONERROR, 1L); - curl_easy_setopt(curl, CURLOPT_VERBOSE, 1L); - + if (verbose && screen) { + curl_easy_setopt(curl, CURLOPT_VERBOSE, 1L); + curl_easy_setopt(curl, CURLOPT_STDERR, (void *) screen); + } if (!verify) { curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 0L); curl_easy_setopt(curl, CURLOPT_SSL_VERIFYHOST, 0L); diff --git a/unittest/commands/test_simple_commands.cpp b/unittest/commands/test_simple_commands.cpp index 017d7ee870..d3fef447ac 100644 --- a/unittest/commands/test_simple_commands.cpp +++ b/unittest/commands/test_simple_commands.cpp @@ -36,7 +36,7 @@ #include // whether to print verbose output (i.e. not capturing LAMMPS screen output). -bool verbose = true; +bool verbose = false; namespace LAMMPS_NS { using ::testing::ContainsRegex; @@ -565,7 +565,6 @@ TEST_F(SimpleCommandsTest, Geturl) platform::unlink("myindex.html"); if (Info::has_curl_support()) { BEGIN_CAPTURE_OUTPUT(); - command("shell curl -v -o myindex.html https://www.lammps.org/index.html"); command("geturl https://www.lammps.org/index.html"); command("geturl https://www.lammps.org/index.html output myindex.html"); END_CAPTURE_OUTPUT(); From 7f8bcbd93a98e7e43b33c3aade9d1a65ffc14474 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Wed, 7 Aug 2024 14:01:23 -0400 Subject: [PATCH 14/15] document "verbose" keyword to "geturl" --- doc/src/geturl.rst | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/doc/src/geturl.rst b/doc/src/geturl.rst index 5d033c43a3..4087bf5828 100644 --- a/doc/src/geturl.rst +++ b/doc/src/geturl.rst @@ -12,13 +12,14 @@ Syntax * url = URL of the file to download * zero or more keyword argument pairs may be provided -* keyword = *output* or *verify* or *overwrite* +* keyword = *output* or *verify* or *overwrite* or *verbose* .. parsed-literal:: *output* filename = write to *filename* instead of inferring the name from the URL *verify* yes/no = verify SSL certificate and hostname if *yes*, do not if *no* *overwrite* yes/no = if *yes* overwrite the output file in case it exists, do not if *no* + *verbose* yes/no = if *yes* write verbose debug output from libcurl to screen, do not if *no* Examples """""""" @@ -50,6 +51,13 @@ The *overwrite* keyword determines whether a file should be overwritten if it already exists. If the argument is *no*, then the download will be skipped if the file exists. +The *verbose* keyword determines whether a detailed protocol of the steps +performed by libcurl is written to the screen. Using the argument *yes* +can be used to debug connection issues when the *geturl* command does not +behave as expected. If the argument is *no*, geturl will operate silently +and only report the error status number provided by libcurl, in case of a +failure. + ---------- Restrictions From eac7c6a8ed8b843d82234a0a444af7e89b19c477 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Thu, 8 Aug 2024 11:12:30 -0400 Subject: [PATCH 15/15] rephrase --- doc/src/geturl.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/src/geturl.rst b/doc/src/geturl.rst index 4087bf5828..0ca0ce0cd3 100644 --- a/doc/src/geturl.rst +++ b/doc/src/geturl.rst @@ -42,10 +42,10 @@ large variety of protocols including "http", "https", "ftp", "scp", The *output* keyword can be used to set the filename. By default, the last part of the URL is used. -The *verify* keyword allows to turn on or off whether ``libcurl`` will validate -the SSL certificate and hostname for encrypted connections. Turning this off -may be required when using a proxy or connecting to a server with a self-signed -SSL certificate. +The *verify* keyword determines whether ``libcurl`` will validate the +SSL certificate and hostname for encrypted connections. Turning this +off may be required when using a proxy or connecting to a server with a +self-signed SSL certificate. The *overwrite* keyword determines whether a file should be overwritten if it already exists. If the argument is *no*, then the download will be skipped