Update documentation

Makefile.nmake

@@ -1,4 +1,5 @@
-PYTHON27_PREFIX=C:\Python27
+PYTHON27_PREFIX=
+# PYTHON27_PREFIX=C:\Python27
 PYTHON27_HEADERS=$(PYTHON27_PREFIX)\include
 PYTHON27_LIBS=$(PYTHON27_PREFIX)\libs
 

NOTES.md

@@ -7,18 +7,18 @@ huku <[[email protected]](mailto:[email protected])>
 
 ## Converting C datatypes to Python PyObjects
 
-Most functions exported to Python are simple wrappers around the low level C API 
+Most functions exported to Python are simple wrappers around the low level C API
 offered by XED2. To be properly returned to the user, the return values of those
-C functions must be converted to one of the datatypes recognized by the Python 
-runtime (i.e. **PyObject** pointers). For the sake of developing **pyxed**, I
+C functions must be converted to one of the datatypes recognized by the Python
+runtime (i.e. `PyObject` pointers). For the sake of developing **pyxed**, I
 settled down to the following set of simple guidelines:
 
-  * When a XED2 function returns **xed_uint_t** to indicate a true/false result,
-    or **xed_bool_t** (also **typedef**'ed to **unsigned int**), use 
-    **PyBool_FromLong()** to retrieve the corresponding Python object.
+  * When a XED2 function returns `xed_uint_t` to indicate a true/false result,
+    or `xed_bool_t` (also `typedef`'ed to `unsigned int`), use `PyBool_FromLong()`
+    to retrieve the corresponding Python object.
 
-  * When functions return arbitrary values of type **xed_uint_t**, use
-    **PyLong_FromUnsignedLong()**.
+  * When functions return arbitrary values of type `xed_uint_t`, use
+    `PyLong_FromUnsignedLong()`.
 
-  * For return values of type **xed_*_enum_t**, use **PyInt_FromLong()**
-    (according to the C standard, enumerations are treated as **int** values).
+  * For return values of type `xed_*_enum_t`, use `PyInt_FromLong()`
+    (according to the C standard, enumerations are treated as `int` values).

README.md

@@ -12,88 +12,72 @@ it doesn't provide any high level abstractions.
 
 ## Compiling pyxed
 
-**pyxed** comes with Makefiles for the most widely used platforms, namely
-Microsoft Windows, MacOS X and Linux. All Makefiles require that you edit them
-and set **XED_PREFIX** appropriately. In order to compile the Python 3 
-module, you will need to initialize the sub-modules:
+### Linux & MacOS X
 
-```shell script
-$ git submodule update --init --recursive
-````
+The **pyxed** build process is based on `setuptools` and should work on both
+Python 3.x and Python 2.x, even though the latter is obsolete.
 
-### Linux
+Begin by cloning **pyxed** and its dependencies:
 
-There are two methods for compiling **pyxed**: Using the make file (Python 2 only)
-or using the Python distools.
+    $ git submodule update --init --recursive
 
-#### Makefile (Python 2)
+Create a new virtual environment for installing and testing:
 
-Compiling on Linux requires GCC to be installed (chances are it is). Just open a
-terminal, enter **pyxed**'s top-level directory and run **make**.
+    $ python -m venv /tmp/pyxed-venv               # Python 3.x
+    $ virtualenv --python=python2 /tmp/pyxed-venv  # Python 2.x
 
-#### Python Distools (Python 2 and 3)
+Build and install **pyxed**:
 
-Simply build the module:
+    $ . /tmp/pyxed-venv/bin/activate
+    $ python setup.py build
+    $ python setup.py install
 
-```shell script
-$ python3 setup.py build
-````
+And, last but not least, make sure everything works as expected:
 
+    $ pip install pytest
+    $ pytest tests/
 
-### MacOS X
 
-Compiling on MacOS X requires the XCode command line utilities to be installed.
-Just open a terminal, enter **pyxed**'s top-level directory and run **make**.
-
-To test that everything works as expected, use the following command:
+### Notes on MacOS X
 
-```sh
-$ PYTHONPATH=. python examples/dump_asm.py 41414141
-```
+Compiling on MacOS X requires the XCode command line utilities to be installed.
 
 Depending on the XED version, you might get the following error when trying to
 import **pyxed** in your project.
 
-```
-Traceback (most recent call last):
-  File "<string>", line 1, in <module>
-ImportError: dlopen(pyxed.so, 2): Library not loaded: obj/libxed.dylib
-  Referenced from: pyxed.so
-  Reason: unsafe use of relative rpath obj/libxed.dylib in pyxed.so with restricted binary
-```
+    Traceback (most recent call last):
+      File "<string>", line 1, in <module>
+    ImportError: dlopen(pyxed.so, 2): Library not loaded: obj/libxed.dylib
+      Referenced from: pyxed.so
+      Reason: unsafe use of relative rpath obj/libxed.dylib in pyxed.so with restricted binary
 
 This is a problem related to hardcoded **rpath** values in Intel's **libxed.dylib**.
 To fix it, run the following command after substituting **/path/to/libxed.dylib**
 with the actual path of **libxed.dylib** in your filesystem.
 
-```sh
-$ otool -L pyxed.so | grep libxed.dylib
-    obj/libxed.dylib
-$ install_name_tool -change obj/libxed.dylib /path/to/libxed.dylib pyxed.so
-```
+    $ otool -L pyxed.so | grep libxed.dylib
+        obj/libxed.dylib
+    $ install_name_tool -change obj/libxed.dylib /path/to/libxed.dylib pyxed.so
 
 
 ### Microsoft Windows
 
-Compiling on Microsoft Windows requires Visual Studio to be installed. Just open
-a console, enter **pyxed**'s top-level directory and set **PYTHON27_PREFIX** in
-**Makefile** to the location where Python is installed on your system. Then, run
-the following commands to build a 32-bit binary:
+Compiling on Microsoft Windows requires Visual Studio to be installed.
 
-```
-C:\pyxed> "C:\Program Files (x86)\Microsoft Visual Studio 10.0\VC\vcvarsall.bat"
-C:\pyxed> nmake /F Makefile.nmake
-```
+First set `PYTHON27_PREFIX` and `XED_PREFIX` in **Makefile.nmake** to the location
+of Python and XED on your system accordingly. Then, run the following commands
+to build a 32-bit binary:
+
+    C:\pyxed> "C:\Program Files (x86)\Microsoft Visual Studio 10.0\VC\vcvarsall.bat"
+    C:\pyxed> nmake /F Makefile.nmake
 
 Or the following to build a 64-bit binary:
 
-```
-C:\pyxed> "C:\Program Files (x86)\Microsoft Visual Studio 10.0\VC\vcvarsall.bat" amd64
-C:\pyxed> nmake /F Makefile.nmake
-```
+    C:\pyxed> "C:\Program Files (x86)\Microsoft Visual Studio 10.0\VC\vcvarsall.bat" amd64
+    C:\pyxed> nmake /F Makefile.nmake
 
-In newer versions of Visual Studio you might need to replace the **amd64**
-argument with **x86\_amd64**.
+In newer versions of Visual Studio you might need to replace the `amd64` argument
+with `x86_amd64`.
 
 
 ### Compiling for use with IDAPython
@@ -103,25 +87,14 @@ appropriate Python version.
 
 For example, on my MacOS X system, **IDAPython** runs on Python 2.6.x:
 
-```
-Python>sys.version
-2.6.7 (r267:88850, Oct 11 2012, 20:15:00)
-[GCC 4.2.1 Compatible Apple Clang 4.0 (tags/Apple/clang-418.0.60)]
-```
+    Python>sys.version
+    2.6.7 (r267:88850, Oct 11 2012, 20:15:00)
+    [GCC 4.2.1 Compatible Apple Clang 4.0 (tags/Apple/clang-418.0.60)]
 
 To make **pyxed** work correctly I had to replace **python2.7-config** with
 **python2.6-config** in **Makefile**.
 
 
-### Precompiled binaries
-
-Experimental precompiled binaries for Microsoft Windows can be downloaded from
-[here](https://www.grhack.net/pyxed-vs2012-xed_2016_02_02.tgz). The tarball
-includes both a 32-bit and a 64-bit release of **pyxed**.
-
-Debian packages are also planned for the near future.
-
-
 ## Using pyxed
 
 For information on how to use **pyxed**, have a look at **examples/**.
@@ -130,8 +103,7 @@ If your compiler throws a warning, if you happen to hit a bug, or if you have
 any comments or suggestions please let me know.
 
 
-## References
-
-  * XED [downloads](https://software.intel.com/en-us/articles/xed-x86-encoder-decoder-software-library)
-  * XED [documentation](https://software.intel.com/sites/landingpage/xed/ref-manual/html/index.html)
+# Links
 
+  * XED [source code](https://github.com/intelxed)
+  * XED [documentation](https://intelxed.github.io/)

TODO

@@ -1,4 +1,3 @@
 2014-12-23 huku <[email protected]>
 
     * Add new class `pyxed.Encoder'.
-