stderred 项目技术文档

本文档将详细介绍如何安装、使用及配置 stderred 项目，该项目能够将标准错误输出（stderr）染成红色，以便与标准输出（stdout）区分。

1. 安装指南

首先，您需要克隆项目仓库：

$ git clone git://github.com/ku1ik/stderred.git
$ cd stderred

确保在以下步骤中使用的 libstderred.so 路径是绝对路径。

对于 Linux 和 FreeBSD

确保安装了编译所需的 cmake 和 gcc 工具链：

• Ubuntu 用户：

sudo apt-get install build-essential cmake

• Fedora 用户：

sudo yum install make cmake gcc gcc-c++

• FreeBSD 用户：

pkg install cmake

然后编译项目：

$ make

在 shell 配置文件（如 .bashrc 或 .zshrc）中导出 LD_PRELOAD 变量：

export LD_PRELOAD="/absolute/path/to/stderred/build/libstderred.so${LD_PRELOAD:+:$LD_PRELOAD}"

多架构系统

在某些 Linux 发行版上，您可以在 64 位系统上安装 32 位软件包。然而，64 位编译的共享库不能与 32 位二进制文件一起使用。幸运的是，Linux 的动态链接器支持动态字符串令牌（DST），它允许在运行二进制文件时动态替换 LD_PRELOAD 变量中的 $LIB 令牌。

您可以为两种架构编译 stderred，然后自动使用正确的版本：

$ make 32 && make 64

并在 shell 配置中这样导出 LD_PRELOAD：

export LD_PRELOAD="/path/to/stderred/$LIB/libstderred.so${LD_PRELOAD:+:$LD_PRELOAD}"

请注意，Ubuntu 不支持 $LIB 令牌。

对于 OSX

编译项目：

$ make

在 shell 配置文件中导出 DYLD_INSERT_LIBRARIES 变量：

export DYLD_INSERT_LIBRARIES="/absolute/path/to/build/libstderred.dylib${DYLD_INSERT_LIBRARIES:+:$DYLD_INSERT_LIBRARIES}"

通用库

OSX 通过支持所谓的“通用”库来解决多架构问题，这种库包含为 32 位和 64 位架构编译的代码副本。

如果要构建通用库，请使用以下命令：

$ make universal

然后如上所述导出 shell 环境变量。

检查是否工作

执行以下命令检查是否正确工作：

$ find -q
$ cat nonexistingfile
$ ls nonexistingfile
$ python -c 'import os; print "Yo!"; os.write(2, "Jola\n\r")'
$ STDERRED_ESC_CODE=$(echo -e '\e[;92m') ruby -e 'puts "Yo!"; warn "Jola"'

"Jola" 应该以红色打印。

2. 使用说明

stderred 通过在 stderr 输出中插入 ANSI 转义码来工作，它不需要重新编译现有的二进制文件。

使用别名

除了通过 shell 配置文件全局启用外，您还可以为特定命令创建别名以选择性染红 stderr：

$ alias stderred="LD_PRELOAD=/absolute/path/to/build/libstderred.so\${LD_PRELOAD:+:\$LD_PRELOAD}"
$ stderred java lol

3. 项目 API 使用文档

stderred 主要通过环境变量进行配置。以下是几个关键的配置选项：

自定义颜色代码

如果您希望使用其他颜色或添加额外的转义码（如加粗/高亮、斜体、不同背景），可以导出 STDERRED_ESC_CODE 变量：

bold=$(tput bold || tput md)
red=$(tput setaf 1)
export STDERRED_ESC_CODE=`echo -e "$bold$red"`

程序黑名单

某些程序可能会错误地使用 stderr 打印信息。如果您希望为特定程序关闭 stderred，可以导出 STDERRED_BLACKLIST 变量：

export STDERRED_BLACKLIST="^(bash|test.*)$"

4. 项目安装方式

项目安装方式已在“安装指南”中详细说明。简而言之，您需要克隆仓库、编译代码，并将 LD_PRELOAD 或 DYLD_INSERT_LIBRARIES 环境变量设置为指向编译出的共享库的路径。