Skip to content

Commit

Permalink
update readme
Browse files Browse the repository at this point in the history
  • Loading branch information
CamJN committed Nov 30, 2023
1 parent fd5201b commit 36b230b
Showing 1 changed file with 7 additions and 8 deletions.
15 changes: 7 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
<h1><img src="logo.svg" width="200" alt="getargv"></h1>

# -> placeholder for ci badge <-
[![C++/make CI](https://github.com/getargv/getargv++/actions/workflows/actions.yml/badge.svg?event=push)](https://github.com/getargv/getargv++/actions/workflows/actions.yml)
[![C++/make CI](https://github.com/getargv/getargv.cpp/actions/workflows/actions.yml/badge.svg)](https://github.com/getargv/getargv.cpp/actions/workflows/actions.yml)

`libgetargv++` is a library that allows you to get the arguments that were passed to another running process on macOS. It is intended to provide roughly the same functionality as reading from `/proc/<pid>/cmdline` on Linux. On macOS this is done by parsing the output of the `KERN_PROCARGS2` sysctl, which is <span title="always, in my observation">very often</span> implemented [incorrectly](https://getargv.narzt.cam/hallofshame.html), due to the overlooked possibility of leading empty arguments passed to the target process.

Expand All @@ -19,7 +18,7 @@ You can download a [pre-built library with headers](http://url1), or an [install

### Step 2: Installing

The simplest way to install this lib is via homebrew, just run `brew tap getargv/tap` and then `brew install libgetargv++`. If you don't use homebrew, then the next easiest way to install this lib is if you downloaded the installer package, which you can simply double click to be guided through the installation via a wizard. If you want to have absolute control over the installation you can unpack the pre-built library downloaded from GitHub and put it somewhere your compiler will pick it up, such as `/usr/local/lib` and put the headers somewhere like `/usr/local/include/libgetargv++`.
The simplest way to install this lib is via Homebrew, just run `brew tap getargv/tap` and then `brew install libgetargv++`. If you don't use Homebrew, then the next easiest way to install this lib is if you downloaded the installer package, which you can simply double click to be guided through the installation via a wizard. If you want to have absolute control over the installation you can unpack the pre-built library downloaded from GitHub and put it somewhere your compiler will pick it up, such as `/usr/local/lib` and put the headers somewhere like `/usr/local/include/libgetargv++`.

### Step 3: Environment

Expand All @@ -29,22 +28,22 @@ Be sure that your compiler can find this lib by checking the library and header
echo | clang++ -c -v -x c++ - 2>&1 | sed -Ee '/search starts here/,/End of search list/!d;/End of search list/q'
```

\attention On Apple Silicon macs, homebrew installs native packages in `/opt`,
\attention On Apple Silicon (ARM) Macs, Homebrew installs native packages in `/opt`,
and puts Intel libraries in `/usr/local`, so your compiler will only
automatically pick up Intel libraries, which is almost certainly not what you
want. You need to explicitly exclude `/usr/local` from your search paths in
this case and add `/opt/`.

### System Requirements

macOS is required as this is a macOS specific `sysctl`, even BSD does not implement it. Your system must support `sysctl` and `KERN_PROCARGS2`, which probably means macOS [10.3](https://github.com/CamJN/xnu/blob/b52f6498893f78b034e2e00b86a3e146c3720649/bsd/sys/sysctl.h#L332) or later, though I haven't tested versions older than 10.7. You'll also need a non-ancient clang++ (c++11 is required, c++20 is the default target) you can override the c++ std by setting `CXXFLAGS="--std=c++11 -O3 -Iinclude"`.
macOS is required as this is a macOS specific `sysctl`, even BSD does not implement it. Your system must support `sysctl` and `KERN_PROCARGS2`, which probably means macOS [10.3](https://github.com/apple-oss-distributions/xnu/blob/xnu-517/bsd/sys/sysctl.h#L332) or later, though I haven't tested versions older than 10.7. You'll also need a non-ancient Clang++ (C++11 is required, C++20 is the default standard on Clang++ versions > 13, otherwise C++17) you can override the C++ std by setting `CXXFLAGS="--std=c++11 -O3 -Iinclude"`.

## Building libgetargv++

To make `libgetargv++`:

- Install `libgetargv` to your system (see below).
- Clone [this repo](https://github.com/getargv/getargv++) and run `make`.
- Clone [this repo](https://github.com/getargv/getargv.cpp) and run `make`.

## Building libgetargv

Expand All @@ -56,7 +55,7 @@ I've built `libgetargv` on macOS 10.7-13, using only the CLT package, not the fu

Run `make -C test`.

I've tested libgetargv++ on macOS 10.7-13, and run CI against all available GitHub hosted macOS runners, with plans to standup a CI cluster of VMs once I acquire appropriate hardware.
I've tested libgetargv++ on macOS 10.7-14, and run CI against all available GitHub hosted macOS runners, with plans to standup a CI cluster of VMs once I acquire appropriate hardware.

## Usage

Expand All @@ -66,7 +65,7 @@ Do you just want to print the arguments to stdout or look at the bytes of the ar

### Step 2: Choosing a constructor

If you want to get a c++ type then `Argv::as_string()` or ArgvArgc::as_string_array()` are your friends, if you want just the bytes, then `Argv()` or `Argv::as_bytes()` are for you, and if you want to look at the args individually then `ArgvArgc()` or `ArgvArgc::as_array()` are what you want.
If you want to get a C++ type then `Argv::as_string()` or ArgvArgc::as_string_array()` are your friends, if you want just the bytes, then `Argv()` or `Argv::as_bytes()` are for you, and if you want to look at the args individually then `ArgvArgc()` or `ArgvArgc::as_array()` are what you want.

### Step 3: Iterating

Expand Down

0 comments on commit 36b230b

Please sign in to comment.