Difference between revisions of "Forth Bridge"

From Infinity Wiki
Jump to navigation Jump to search
(Created page with "Forth Bridge is the fourth full-system preview release of Infinity. Forth Bridge showcases low-level Python bindings for libi8x, which are used by the note tester [I8X] and th...")
 
Line 2: Line 2:
  
 
__TOC__
 
__TOC__
 
  
 
== Changes since Infinity Third Eye ==
 
== Changes since Infinity Third Eye ==
Line 23: Line 22:
 
* All testcases have been updated to use <code>@TestCase.provide</code>.
 
* All testcases have been updated to use <code>@TestCase.provide</code>.
  
 +
== Building Infinity Forth Bridge ==
  
== Building Infinity Forth Bridge ==
+
Note that there's presently no PIP package for the libi8x Python bindings, so for this release you'll have to build them from source.  Note also that the order of things has changed for this release, it's necessary to build libi8x before I8C in order to use the new interpreter for the glibc build step.
  
 
=== Build libi8x with the shim libthread_db ===
 
=== Build libi8x with the shim libthread_db ===
Line 42: Line 42:
 
You should see an <code>examples/libthread_db.so.1</code> symbolic link if it worked.
 
You should see an <code>examples/libthread_db.so.1</code> symbolic link if it worked.
  
 
+
=== Build libi8x Python bindings ===
=== Install libi8x Python bindings ===
 
  
 
Now you need to build and install the Python bindings that the note compiler needs:
 
Now you need to build and install the Python bindings that the note compiler needs:
Line 51: Line 50:
  
 
You should be able to execute <code>import _libi8x</code> in Python without error if this step worked.
 
You should be able to execute <code>import _libi8x</code> in Python without error if this step worked.
 +
 +
Note that for this release the Python bindings statically link libi8x; there's no need to <code>make install</code> libi8x.
 +
 +
=== Build I8C ===
 +
 +
The note compiler must be built from source for this release:
 +
git clone <nowiki>https://gitlab.com/gbenson/i8c.git</nowiki>
 +
cd i8c
 +
git branch forth-bridge infinity-forth-bridge
 +
git checkout forth-bridge
 +
python setup.py test  ''# optional''
 +
python setup.py install --user
 +
 +
You should see <code>using libi8x interpreter (experimental)</code> near the top of the <code>python setup.py test</code> output if the libi8x bindings were successfully installed.
 +
 +
=== Create a test build of glibc with Infinity notes ===
 +
 +
The command <code>i8c</code> needs to be in your path before you continue.  If you're following this guide it'll be in <code>~/.local/bin/i8c</code>, so you may need to add <code>~/.local/bin</code> to your path.  Alternatively you can omit the <code>--user</code> and install I8C globally on your system.  However you install it, you need to be able to enter this exact command:
 +
i8c --version | head -n 1
 +
 +
and see this exact output:
 +
I8C 0.0.6
 +
 +
Once you have I8C installed you can proceed to build glibc:
 +
 +
mkdir -p glibc/build
 +
git clone <nowiki>https://gitlab.com/gbenson/glibc.git</nowiki> glibc/src
 +
cd glibc/src
 +
git branch forth-bridge infinity-forth-bridge
 +
git checkout forth-bridge
 +
cd ../build
 +
../src/configure --prefix=/usr --with-infinity
 +
make
 +
 +
<code>--with-infinity</code> is assumed if you have I8C installed, but specifiying it explicitly here forces <code>configure</code> to check the version for you.
 +
 +
You should be able to see Infinity notes in libpthread.so and ld.so if everything worked. Both
 +
readelf -n nptl/libpthread.so
 +
readelf -n elf/ld.so
 +
 +
should list several notes with owner "GNU" and unknown type 0x2323:
 +
Displaying notes found at file offset 0x0002144c with length 0x00000378:
 +
  Owner                Data size Description
 +
  GNU                  0x0000006d Unknown note type: (0x00002323)
 +
  GNU                  0x0000007d Unknown note type: (0x00002323)
 +
  GNU                  0x000000cc Unknown note type: (0x00002323)
 +
  GNU                  0x0000009f Unknown note type: (0x00002323)
 +
  GNU                  0x0000005f Unknown note type: (0x00002323)
 +
  GNU                  0x0000005b Unknown note type: (0x00002323)
 +
 +
See https://sourceware.org/glibc/wiki/Testing/Builds for more information about glibc test builds.
 +
 +
== Things to do with Infinity Forth Bridge ==
 +
 +
=== Run the note tester on the glibc you built ===
 +
 +
The note tester [[I8X]] is hooked into glibc's <code>make&nbsp;check</code>, but lets run it directly:
 +
  cd ''/path/to''/glibc/build
 +
  i8x -I. -i nptl/libpthread.so ../src/nptl/tst-infinity-*.py
 +
 +
You should see some output as to the result of the tests, and all tests should pass.  You should see <code>using libi8x interpreter (experimental)</code> near the top of the output if the libi8x bindings were successfully installed.  If you see <code>using Python interpreter (deprecated)</code> then something went wrong.
 +
 +
To run with glibc's make&nbsp;check, try this:
 +
  cd ''/path/to''/glibc/build
 +
  make subdirs=nptl check
 +
 +
I8X's output will be in <code>nptl/tst-infinity.out</code>, and the result that glibc's make&nbsp;check consumes will be in <code>nptl/tst-infinity.test-result</code>.  Again, you should see <code>using libi8x interpreter (experimental)</code> near the top of I8X's output.
 +
 +
=== GDB Things ===
 +
 +
There's no GDB-specific changes in this release, but GDB things from previous releases are still relevant.  See:
 +
* [[Third Eye#Build patched GDB]]
 +
* [[Third Eye#Things to do with Infinity Third Eye]]

Revision as of 03:28, 10 July 2017

Forth Bridge is the fourth full-system preview release of Infinity. Forth Bridge showcases low-level Python bindings for libi8x, which are used by the note tester [I8X] and the note compiler's testsuite. Forth Bridge will be released July 10, 2017.

Changes since Infinity Third Eye

libi8x

  • libi8x now has low-level Python bindings (to be supplemented by a high-level layer in a future release.)
  • The relocation interface has changed.
  • Userdata is now immutable once set.
  • A number of bugs in the LEB128 decoders and function unregistration are now fixed.
  • A number of previously-internal functions are now public.
  • A new error code I8X_NATCALL_FAILED has been introduced.

I8C

  • I8X now uses libi8x to execute Infinity functions if libi8x and its Python bindings are installed.
  • Infinity functions provided by testcases must now be identified using the @TestCase.provide decorator.
  • The function TestCase.implement has been removed.
  • The interpreter context is no longer accessible as TestCase.i8ctx. Infinity functions should now be executed using TestCase.call.

glibc

  • All testcases have been updated to use @TestCase.provide.

Building Infinity Forth Bridge

Note that there's presently no PIP package for the libi8x Python bindings, so for this release you'll have to build them from source. Note also that the order of things has changed for this release, it's necessary to build libi8x before I8C in order to use the new interpreter for the glibc build step.

Build libi8x with the shim libthread_db

To build libi8x with the shim libthread_db you first need to install the elfutils libelf development files. For Fedora and RHEL this is the elfutils-libelf-devel RPM. For Debian and Ubuntu the package you need is libelf-dev. Either way, once done you should see /usr/include/libelf.h on your system.

Once that's there, clone and build libi8x:

 git clone https://gitlab.com/gbenson/libi8x.git
 cd libi8x
 git branch forth-bridge infinity-forth-bridge
 git checkout forth-bridge
 ./autogen.sh
 ./configure
 make
 make check  # optional

You should see an examples/libthread_db.so.1 symbolic link if it worked.

Build libi8x Python bindings

Now you need to build and install the Python bindings that the note compiler needs:

 cd python
 python setup.py test  # optional
 python setup.py install --user

You should be able to execute import _libi8x in Python without error if this step worked.

Note that for this release the Python bindings statically link libi8x; there's no need to make install libi8x.

Build I8C

The note compiler must be built from source for this release:

git clone https://gitlab.com/gbenson/i8c.git
cd i8c
git branch forth-bridge infinity-forth-bridge
git checkout forth-bridge
python setup.py test  # optional
python setup.py install --user

You should see using libi8x interpreter (experimental) near the top of the python setup.py test output if the libi8x bindings were successfully installed.

Create a test build of glibc with Infinity notes

The command i8c needs to be in your path before you continue. If you're following this guide it'll be in ~/.local/bin/i8c, so you may need to add ~/.local/bin to your path. Alternatively you can omit the --user and install I8C globally on your system. However you install it, you need to be able to enter this exact command:

i8c --version | head -n 1

and see this exact output:

I8C 0.0.6

Once you have I8C installed you can proceed to build glibc:

mkdir -p glibc/build
git clone https://gitlab.com/gbenson/glibc.git glibc/src
cd glibc/src
git branch forth-bridge infinity-forth-bridge
git checkout forth-bridge
cd ../build
../src/configure --prefix=/usr --with-infinity
make

--with-infinity is assumed if you have I8C installed, but specifiying it explicitly here forces configure to check the version for you.

You should be able to see Infinity notes in libpthread.so and ld.so if everything worked. Both

readelf -n nptl/libpthread.so
readelf -n elf/ld.so

should list several notes with owner "GNU" and unknown type 0x2323:

Displaying notes found at file offset 0x0002144c with length 0x00000378:
  Owner                 Data size	Description
  GNU                  0x0000006d	Unknown note type: (0x00002323)
  GNU                  0x0000007d	Unknown note type: (0x00002323)
  GNU                  0x000000cc	Unknown note type: (0x00002323)
  GNU                  0x0000009f	Unknown note type: (0x00002323)
  GNU                  0x0000005f	Unknown note type: (0x00002323)
  GNU                  0x0000005b	Unknown note type: (0x00002323)

See https://sourceware.org/glibc/wiki/Testing/Builds for more information about glibc test builds.

Things to do with Infinity Forth Bridge

Run the note tester on the glibc you built

The note tester I8X is hooked into glibc's make check, but lets run it directly:

 cd /path/to/glibc/build
 i8x -I. -i nptl/libpthread.so ../src/nptl/tst-infinity-*.py

You should see some output as to the result of the tests, and all tests should pass. You should see using libi8x interpreter (experimental) near the top of the output if the libi8x bindings were successfully installed. If you see using Python interpreter (deprecated) then something went wrong.

To run with glibc's make check, try this:

  cd /path/to/glibc/build
  make subdirs=nptl check

I8X's output will be in nptl/tst-infinity.out, and the result that glibc's make check consumes will be in nptl/tst-infinity.test-result. Again, you should see using libi8x interpreter (experimental) near the top of I8X's output.

GDB Things

There's no GDB-specific changes in this release, but GDB things from previous releases are still relevant. See: