Skip to content

Commit

Permalink
fix mingw build and docs (#320)
Browse files Browse the repository at this point in the history 
Fixes warnings encountered during MinGW builds due to type mismatches.
Also updates the build documentation to include more specific instructions
for MinGW platforms.

This partially resolves #318, which can be referenced for more details.
It does not fix the build on older versions of MinGW, which will be
handled in a separate change if needed.

The additional information on building on MinGW and MSYS2 may also
help #303.
  • Loading branch information
@goatshriek
goatshriek committed Dec 26, 2022
1 parent c1adb39 commit a7b4b1a
Show file tree
Hide file tree
Showing 4 changed files with 92 additions and 37 deletions.
95 changes: 76 additions & 19 deletions INSTALL.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ Debian and Ubuntu. The package can be installed with the usual command:

```sh
# you might need sudo (or root privileges) to install
dpkg -i stumpless-2.0.0-amd64.deb
dpkg -i stumpless-2.2.0-amd64.deb
```


Expand All @@ -27,7 +27,7 @@ installed in the traditional way as well:

```sh
# again, make sure you have the correct permissions
rpm -i stumpless-2.0.0-x86_64.rpm
rpm -i stumpless-2.2.0-x86_64.rpm
```


Expand All @@ -42,7 +42,7 @@ files.
# you might need to do this with sudo!
# make sure your permissions allow you to write to the install locations
cd /usr
./stumpless-2.0.0.sh
./stumpless-2.2.0.sh
```


Expand Down Expand Up @@ -70,14 +70,37 @@ branches, or make any changes yourself.

## Prepping your System
Since there are so many possible ways to set up an environment, stumpless does
not provide any single way to do this. However, here are some one-liners that
not provide any single way to do this. However, here are some snippets that
can get everything installed for you in some common environments.

Note that some depenencies for developing Stumpless are left out of these
snippets, most notably Git, Ruby, and Valgrind. For a full list of dependencies
check the [dependency documentation](./docs/dependencies.md), which lists all of
the tools you might need. The snippets below allow you to build and test the
library, as well as build the documentation for it.

Similarly, if you only want to build the library, you may not need all of these.
A C++ compiler is only needed to build the test suites, and doxygen is only
needed if you build the documentation. If you only want to build the library and
immediately install/use it, you will only need cmake and a C toolchain.

For Linux systems with a package manager like `apt`, you can install the needed
tools (for a GNU toolchain) with something like the following:

```sh
sudo apt-get install git cmake make gcc g++ doxygen
# for distributions using apt, such as Ubuntu or Debian:
sudo apt-get install cmake make gcc g++ doxygen

# for distributions that use pacman such as Arch Linux or MSYS2:
pacman -S cmake make gcc doxygen

# For MinGW be sure that you use the MinGW packages, such as in the following
# pacman invocation. Be sure that you are in a MinGW shell when building this
# way. For example, MSYS2 provides some MinGW terminals.
pacman -S $MINGW_PACKAGE_PREFIX-cmake \
$MINGW_PACKAGE_PREFIX-make \
$MINGW_PACKAGE_PREFIX-gcc \
$MINGW_PACKAGE_PREFIX-doxygen
```

Cygwin lacks a package manager in the environment itself, requiring packages to
Expand All @@ -86,7 +109,7 @@ GUI, or if you want to just do it via command line, you can do something like
this:

```sh
setup-x86_64.exe -q -P git,cmake,make,gcc-core,gcc-g++,doxygen
setup-x86_64.exe -q -P cmake,make,gcc-core,gcc-g++,doxygen
```


Expand All @@ -97,6 +120,8 @@ using `make` from a fresh clone.

```sh
# cloning the latest version of the source tree
# if you don't want to use git, you can download a zip of the sources from
# github
git clone [email protected]:goatshriek/stumpless.git

# creating a new build directory
Expand All @@ -114,18 +139,35 @@ Other environments should be built according to their normal style. For example
Visual Studio provides a CMake menu in the IDE that will display all available
targets.

CMake will use the build toolchain it feels is best, but on systems with
multiple available toolchains you may want to override this. For example, MinGW
systems may default to using Ninja, instead of the MinGW toolchain. In these
situations, you'll likely want to specify a
[generator](https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html)
during the configuration stage. Sticking with the MinGW case, this might look
like this:

```sh
# run within the MinGW shell, in our fresh build directory
cmake -G "MinGW Makefiles" ../stumpless
```

If you're unsure of the build commands for the toolchain on your system, then
cmake can run these commands for you if you invoke it in build mode.
cmake can run these commands for you if you invoke it in
[build mode](https://cmake.org/cmake/help/latest/manual/cmake.1.html#build-a-project).
This is especially handy in environments like Visual Studio or MinGW, where the
build toolchain might require prefixes and/or options to work properly.

```sh
# build the `all` target using whatever toolchain cmake detected during the
# configuration stage
# build the default target ("all") using whatever toolchain cmake detected
# during the configuration stage
# the argument to the `--build` parameter is the root of the folder where we
# ran the original cmake configuration command
cmake --build . --target all
cmake --build .

# build and run the test suite the same way
cmake --build . --target all
# we can build and run any other target with the `--target` option
# for example, this invocation builds and runs the test suite
cmake --build . --target check
```

The type of build can be changed at configuration time by defining the
Expand Down Expand Up @@ -157,8 +199,20 @@ The rest of this documentation uses make commands for simplicity, but for any
target you can build it using cmake build mode if you need truly portable
command line invocation.

## Verifying your Build

## Building Documentation
The documentation for the library can be built using the `docs` target. Note
that this target will only be available if doxygen was detected during the
configuration of the system.

```sh
# the resulting documentation will appear in a folder named docs in the build
# directory
make docs
```


## Verifying your Build
If you want to run the test suite on the library during development or as a
sanity check before installation, you can use the `check` target to run all
tests and display the results. If you're concerned that the build may not work
Expand All @@ -179,8 +233,8 @@ will download and build the Google Benchmark library in order to run.
make bench
```

## Installing your Build

## Installing your Build
You can use the install target to install the library on your machine after the
build.

Expand Down Expand Up @@ -248,21 +302,24 @@ cat install_manifest.txt
# <output truncated>
```

### Uninstalling
Some tools, such as Visual Studio, will run the installation step for you. In
Visual Studio 2022 for example, this is in the `Build->Install stumpless` menu.


### Uninstalling
There is currently no uninstall target supported, so removal of the library
and its include files must be done manually if it is no longer needed. Please
submit an issue on the project's Github site if you feel that you need a build
target providing this feature. For the time being, you can run the contents
of the `install_manifest.txt` file (generated during the install) through `rm`
like this:
target providing this feature. If you are on a Linux system, you can run the
contents of the `install_manifest.txt` file (generated during the install)
through `rm` like this:

```sh
xargs rm < install_manifest.txt
```

## C++ Library

## C++ Library
If you want to build, test, and install the C++ bindings for stumpless as well,
you will need to modify the above steps slightly.

Expand Down
4 changes: 2 additions & 2 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,11 +20,11 @@
## Key Features
Stumpless offers a robust set of features to make logging in C faster and
easier:
* structured and unstructured logging to suit your needs
* easy logging to [lots of things](#what-can-it-log-to) like Splunk, rsyslog,
journald, the Windows Event Log, and more!
* structured and unstructured logging to suit your needs
* interoperable with common log daemons and libraries
* cross-platform builds on Linux, Windows, Mac, Cygwin, and more
* builds for Linux, Windows, Mac, MinGW, MSYS2, Cygwin, and more
* completely thread safe
* can be adjusted or removed during compilation for zero runtime impact
* localized for multiple languages :brazil: :bulgaria: :cn: :czech_republic:
Expand Down
10 changes: 4 additions & 6 deletions docs/dependencies.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -43,12 +43,10 @@ the public header files. Documentation can also be generated using `doxygen`.
This is done using the `docs` build target, which will only be available if
doxygen is detected on the build system.

You can avoid downloading the repo and building the documentation by visiting
the project Github Pages website, (code is in the `gh-pages` branch of the
repository). This contains several of the documents in the `docs` folder of the
repository in a prettier format, and also uses `m.css` to generate a more
appealing and mobile-friendly doxygen page. More information on `m.css` can be
found on the [m.css project page](https://mcss.mosra.cz/).
If you only want to see the docs, you can avoid downloading the repo and
building it by visiting the project
[website](https://goatshriek.github.io/stumpless/), which has documentation for
C and C++ for the latest release.

## Development
If you wish to develop within the stumpless project itself, you will need a few
Expand Down
20 changes: 10 additions & 10 deletions src/config/wel_supported.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1192,15 +1192,15 @@ stumpless_add_wel_event_source( LPCSTR subkey_name,
LPCSTR param_file,
DWORD types_supported ) {
DWORD result = ERROR_SUCCESS;
DWORD subkey_name_length = 0;
int subkey_name_length = 0;
LPCWSTR subkey_name_w;
DWORD source_name_length = 0;
int source_name_length = 0;
LPWSTR source_name_w;
DWORD category_file_length = 0;
int category_file_length = 0;
LPCWSTR category_file_w = NULL;
DWORD event_file_length = 0;
int event_file_length = 0;
LPCWSTR event_file_w = NULL;
DWORD param_file_length = 0;
int param_file_length = 0;
LPCWSTR param_file_w = NULL;

VALIDATE_ARG_NOT_NULL_WINDOWS_RETURN( subkey_name );
Expand All @@ -1209,22 +1209,22 @@ stumpless_add_wel_event_source( LPCSTR subkey_name,
clear_error( );

subkey_name_w = windows_copy_cstring_to_lpwstr( subkey_name,
&subkey_name_length );
&subkey_name_length );
if( !subkey_name_w ) {
result = get_windows_error_code( );
goto finish;
}

source_name_w = windows_copy_cstring_to_lpwstr( source_name,
&source_name_length );
&source_name_length );
if( !source_name_w ) {
result = get_windows_error_code( );
goto cleanup_subkey;
}

if( category_file ) {
category_file_w = windows_copy_cstring_to_lpwstr( category_file,
&category_file_length );
&category_file_length );
if( !category_file_w ) {
result = get_windows_error_code( );
goto cleanup_source;
Expand All @@ -1233,7 +1233,7 @@ stumpless_add_wel_event_source( LPCSTR subkey_name,

if( event_file ) {
event_file_w = windows_copy_cstring_to_lpwstr( event_file,
&event_file_length );
&event_file_length );
if( !event_file_w ) {
result = get_windows_error_code( );
goto cleanup_category;
Expand All @@ -1242,7 +1242,7 @@ stumpless_add_wel_event_source( LPCSTR subkey_name,

if( param_file ) {
param_file_w = windows_copy_cstring_to_lpwstr( param_file,
&param_file_length );
&param_file_length );
if( !param_file_w ) {
result = get_windows_error_code( );
goto cleanup_event;
Expand Down

0 comments on commit a7b4b1a

Please sign in to comment.