* [PATCH] various doc updates, add mwrap(1) manpage
@ 2023-01-09 5:52 Eric Wong
0 siblings, 0 replies; only message in thread
From: Eric Wong @ 2023-01-09 5:52 UTC (permalink / raw)
To: mwrap-public
FreeBSD 12.x doesn't seem to work with the `pkg install'-ed
ruby
---
Documentation/.gitignore | 2 +
Documentation/GNUmakefile | 63 +++++++++++++++++++
Documentation/mwrap.pod | 123 ++++++++++++++++++++++++++++++++++++++
MANIFEST | 4 +-
README | 38 +++++++-----
mwrap.gemspec | 11 +++-
6 files changed, 223 insertions(+), 18 deletions(-)
create mode 100644 Documentation/.gitignore
create mode 100644 Documentation/GNUmakefile
create mode 100644 Documentation/mwrap.pod
diff --git a/Documentation/.gitignore b/Documentation/.gitignore
new file mode 100644
index 0000000..1b0e502
--- /dev/null
+++ b/Documentation/.gitignore
@@ -0,0 +1,2 @@
+mwrap.txt
+mwrap.1
diff --git a/Documentation/GNUmakefile b/Documentation/GNUmakefile
new file mode 100644
index 0000000..14480da
--- /dev/null
+++ b/Documentation/GNUmakefile
@@ -0,0 +1,63 @@
+# Copyright (C) all contributors <mwrap-public@80x24.org>
+# License: GPL-3.0+ <https://www.gnu.org/licenses/gpl-3.0.txt>
+all::
+
+INSTALL = install
+POD2MAN = pod2man
+VERSION := $(shell cd .. && ./VERSION-GEN)
+release := mwrap $(VERSION)
+POD2MAN_OPTS = -v -r '$(release)' --stderr -d 1993-10-02 -c 'mwrap user manual'
+pod2man = $(POD2MAN) $(POD2MAN_OPTS)
+POD2TEXT = pod2text
+POD2TEXT_OPTS = --stderr
+pod2text = $(POD2TEXT) $(POD2TEXT_OPTS)
+
+m1 = mwrap
+m5 =
+m7 =
+
+man1 := $(addsuffix .1, $(m1))
+man5 := $(addsuffix .5, $(m5))
+man7 := $(addsuffix .7, $(m7))
+
+all:: man
+
+man: $(man1) $(man5) $(man7)
+
+prefix ?= $(HOME)
+mandir ?= $(prefix)/share/man
+man1dir = $(mandir)/man1
+man5dir = $(mandir)/man5
+man7dir = $(mandir)/man7
+
+gem-man: man
+ $(INSTALL) -d -m 755 ../man
+ test -z "$(man1)" || $(INSTALL) -m 644 $(man1) ../man
+ test -z "$(man5)" || $(INSTALL) -m 644 $(man5) ../man
+ test -z "$(man7)" || $(INSTALL) -m 644 $(man7) ../man
+
+install-man: man
+ $(INSTALL) -d -m 755 $(DESTDIR)$(man1dir)
+ $(INSTALL) -d -m 755 $(DESTDIR)$(man5dir)
+ test -z "$(man7)" || $(INSTALL) -d -m 755 $(DESTDIR)$(man7dir)
+ $(INSTALL) -m 644 $(man1) $(DESTDIR)$(man1dir)
+ $(INSTALL) -m 644 $(man5) $(DESTDIR)$(man5dir)
+ test -z "$(man7)" || $(INSTALL) -m 644 $(man7) $(DESTDIR)$(man7dir)
+
+%.1 %.5 %.7 : %.pod
+ $(pod2man) -s $(subst .,,$(suffix $@)) $< $@+ && mv $@+ $@
+
+mantxt = $(addsuffix .txt, $(m1) $(m5) $(m7))
+
+txt :: $(mantxt)
+
+all :: txt
+
+%.txt : %.pod
+ $(pod2text) $< $@+
+ touch -r $< $@+
+ mv $@+ $@
+
+clean::
+ $(RM) $(man1) $(man5) $(man7)
+ $(RM) $(addsuffix .txt.gz, $(m1) $(m5) $(m7))
diff --git a/Documentation/mwrap.pod b/Documentation/mwrap.pod
new file mode 100644
index 0000000..6832430
--- /dev/null
+++ b/Documentation/mwrap.pod
@@ -0,0 +1,123 @@
+=head1 NAME
+
+mwrap - run any command under mwrap
+
+=head1 SYNOPSIS
+
+ # to trace a long-running program and access it via $DIR/$PID.sock:
+ MWRAP=socket_dir:$DIR mwrap COMMAND
+
+ # to trace a short-lived command and dump its output to a log:
+ MWRAP=dump_path:$FILENAME mwrap COMMAND
+
+=head1 DESCRIPTION
+
+mwrap is a command-line to automatically add mwrap.so as an
+LD_PRELOAD for any command. It will resolve malloc-family calls
+to a Ruby file and line number, and it can also provide a backtrace
+of native (C/C++) functions for non-Ruby programs.
+
+=head1 ENVIRONMENT
+
+C<MWRAP> is the only environment variable read. It contains multiple
+options delimited by C<,> with names and values delimited by C<:>
+
+=over 4
+
+=item socket_dir:$DIR
+
+This launches an embedded HTTP server in each process and binds it
+to C<$DIR/$PID.sock>. C<curl --unix-socket $DIR/$PID.sock>
+or L<mwrap-rproxy(1p)> (from L<https://80x24.org/mwrap-perl.git>) may
+be used to access various endpoints in the HTTP server.
+
+=item bt:$DEPTH
+
+The backtrace depth for L<backtrace(3)> in addition to the Perl
+file and line number where C<$DEPTH> is a non-negative number.
+
+The maximum allowed value is 32, though values of 5 or less are
+typically useful. Increasing this to even 2 or 3 can significantly
+increase the amount of memory mwrap (and liburcu) itself uses.
+
+This is only useful in conjunction with C<socket_dir>
+
+This may be changed via POST request (see below).
+
+Default: 0
+
+=item dump_path:$FILENAME
+
+Dumps the output at exit to a given filename:
+
+ total_bytes call_count location
+
+In the future, dumping to a self-describing CSV will be supported.
+
+=item dump_fd:$DESCRIPTOR
+
+As with dump_path, but dumps the output to a given file descriptor.
+
+=back
+
+=head1 HTTP POST API
+
+In addition to the various GET endpoints linked via C<http://0/$PID/>,
+there are some POST endpoints which are typically accessed via
+C<curl --unix-socket $DIR/$PID.sock>
+
+=over 4
+
+=item POST http://0/$PID/reset
+
+C<curl --unix-socket $DIR/$PID.sock -XPOST http://0/$PID/reset>
+
+Reset all internal counters. This is not done atomically and does
+not release any memory.
+
+=item POST http://0/$PID/trim
+
+C<curl --unix-socket $DIR/$PID.sock -XPOST http://0/$PID/trim>
+
+Runs L<malloc_trim(3)> with a 0 pad value to release unused memory
+back to the kernel. In our malloc implementation, this is done
+lazily to avoid contention and does not happen unless sleeping threads.
+
+=item POST http://0/$PID/ctl
+
+Set various internal knobs. Currently, C<X-Mwrap-BT> is the
+only knob supported:
+
+C<curl --unix-socket $DIR/$PID.sock -XPOST -HX-Mwrap-BT:1 http://0/$PID/ctl>
+
+Using the C<X-Mwrap-BT> header allows changing the aforementioned
+C<bt:> value to a specified depth level. As with C<bt:>, only make small
+adjustments as the memory cost can increase exponentially with each step.
+
+It is typically a good idea to reset (C<http://0/$PID/reset>) after changing
+the depth on a running process.
+
+Headers other than C<X-Mwrap-BT> may be accepted in the future to
+tweak other settings.
+
+=back
+
+=head1 CONTACT
+
+Feedback welcome via plain-text mail to L<mailto:mwrap-public@80x24.org>
+
+Mail archives are hosted at L<https://80x24.org/mwrap-public/>
+
+=head1 COPYRIGHT
+
+Copyright all contributors L<mailto:mwrap-public@80x24.org>
+
+License: GPL-3.0+ L<https://www.gnu.org/licenses/gpl-3.0.txt>
+
+Source code is at L<https://80x24.org/mwrap.git/>
+
+=head1 SEE ALSO
+
+L<mwrap-rproxy(1)>, L<Devel::Mwrap(3pm)>, L<https://80x24.org/mwrap-perl.git>
+
+=cut
diff --git a/MANIFEST b/MANIFEST
index 4c5be8b..8d4cdd6 100644
--- a/MANIFEST
+++ b/MANIFEST
@@ -2,6 +2,9 @@
.gitignore
.olddoc.yml
COPYING
+Documentation/.gitignore
+Documentation/GNUmakefile
+Documentation/mwrap.pod
MANIFEST
README
Rakefile
@@ -24,4 +27,3 @@ mwrap.gemspec
t/httpd.t
t/test_common.perl
test/test_mwrap.rb
-lib/mwrap/version.rb
diff --git a/README b/README
index 382c5a0..761f87e 100644
--- a/README
+++ b/README
@@ -8,8 +8,8 @@ mwrap wraps all malloc-family calls to trace the Ruby source
location of such calls and bytes allocated at each callsite.
As of mwrap 2.0.0, it can also function as a leak detector
and show live allocations at every call site. Depending on
-your application and workload, the overhead is roughly a 50%
-increase memory and runtime.
+your application and workload, the overhead is roughly a 50-100%
+increase memory and runtime with default settings.
It works best for allocations under GVL, but tries to track
numeric caller addresses for allocations made without GVL so you
@@ -22,15 +22,13 @@ Userspace RCU project: https://liburcu.org/
It does not require recompiling or rebuilding Ruby, but only
supports Ruby 2.7.0 or later on a few platforms:
-* GNU/Linux
-* FreeBSD
+* GNU/Linux (only tested --without-jemalloc, mwrap 3.x provides its own)
-It may work on NetBSD, OpenBSD and DragonFly BSD.
+It may work on FreeBSD, NetBSD, OpenBSD and DragonFly BSD if given
+appropriate build options.
== Install
- # FreeBSD: pkg install liburcu
-
# Debian-based systems: apt-get liburcu-dev
# Install mwrap via RubyGems.org
@@ -64,24 +62,33 @@ or an address retrieved by backtrace_symbols(3). It is
recommended to use the sort(1) command on either of the
first two columns to find the hottest malloc locations.
-mwrap 2.0.0+ also supports a Rack application endpoint,
+mwrap 3.0.0+ also supports an embedded HTTP server
it is documented at:
-https://80x24.org/mwrap/MwrapRack.html
+https://80x24.org/mwrap.git/tree/Documentation/mwrap.pod
== Known problems
* 32-bit machines are prone to overflow (WONTFIX)
-== Public mail archives and contact info:
+* signalfd(2)-reliant code will need latest URCU with commit
+ ea3a28a3f71dd02f (Disable signals in URCU background threads, 2022-09-23)
+ This doesn't affect C Ruby itself, and signalfd(2) use is rare
+ 3rd-party processes.
+
+* Ruby source files over 16.7 million lines long are not supported :P
+
+== Public mail archives (HTTP, Atom feeds, IMAP mailbox, NNTP group, POP3):
* https://80x24.org/mwrap-public/
* nntps://80x24.org/inbox.comp.lang.ruby.mwrap
* imaps://;AUTH=ANONYMOUS@80x24.org/inbox.comp.lang.ruby.mwrap.0
* https://80x24.org/mwrap-public/_/text/help/#pop3
-No subscription will ever be required to post, but HTML mail
-will be rejected:
+No subscription nor real identities will ever be required to obtain support,
+but HTML mail is rejected. Memory usage reductions start with you;
+only send plain-text mail to us and do not top-post. HTML mail and
+top-posting costs everybody memory and bandwidth.
mwrap-public@80x24.org
@@ -89,9 +96,10 @@ will be rejected:
git clone https://80x24.org/mwrap.git
-Send all patches and pull requests (use "git request-pull" to format) to
-mwrap-public@80x24.org. We do not use centralized or proprietary messaging
-systems.
+Send all patches ("git format-patch" + "git send-email") and
+pull requests (use "git request-pull" to format) via email
+to mwrap-perl@80x24.org. We do not and will not use
+proprietary messaging systems.
== License
diff --git a/mwrap.gemspec b/mwrap.gemspec
index dc99924..b6f9e71 100644
--- a/mwrap.gemspec
+++ b/mwrap.gemspec
@@ -1,6 +1,5 @@
git_manifest = `git ls-files 2>/dev/null`.split("\n")
git_ok = $?.success?
-git_manifest << 'lib/mwrap/version.rb'.freeze # generated by ./VERSION-GEN
manifest = File.exist?('MANIFEST') ?
File.readlines('MANIFEST').map!(&:chomp).delete_if(&:empty?) : git_manifest
if git_ok && manifest != git_manifest
@@ -12,11 +11,19 @@ end
version = `./VERSION-GEN`.chomp
$?.success? or abort './VERSION-GEN failed'
+manifest << 'lib/mwrap/version.rb'.freeze
+
+if system(*%w(make -C Documentation man)) ||
+ system(*%w(gmake -C Documentation man))
+ manifest.concat(%w(Documentation/mwrap.1))
+else
+ warn 'failed to build man-page(s), proceeding without them'
+end
Gem::Specification.new do |s|
s.name = 'mwrap'
s.version = version
- s.homepage = 'https://80x24.org/mwrap/'
+ s.homepage = 'https://80x24.org/mwrap.git/'
s.authors = ["mwrap hackers"]
s.summary = 'LD_PRELOAD malloc wrapper for Ruby'
s.executables = %w(mwrap)
^ permalink raw reply related [flat|nested] only message in thread
only message in thread, other threads:[~2023-01-09 5:52 UTC | newest]
Thread overview: (only message) (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2023-01-09 5:52 [PATCH] various doc updates, add mwrap(1) manpage Eric Wong
Code repositories for project(s) associated with this public inbox
https://80x24.org/mwrap.git/
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).